Description
This distribution provides an API for the GeoIP2Precision web services anddatabases. The API alsoworks with the free GeoLite2 databases.
Installation
Maven
We recommend installing this package with Maven.To do this, add the dependency to your pom.xml:
Gradle
Add a reference in your Epi project to the Pixie.Extensions.Maxmind.GeoIp.dll generated by the build Download the GeoLite2 City database to unpack and add the GeoLite2-City.mmdb file to your appdata in your project. My customer's IP was flagged as a proxy, and they claim it's not. What should I do? If you feel that a customer's IP address was flagged incorrectly, please contact our support team via email to support@maxmind.com or the chat tab on our site, and we will have our data review team investigate.
- MaxMind accountIdand licenseKey. You may also set a timeout, specify a specific host, or set the localesfallback order using the methods on the Builder. After you have created the WebServiceClient, you may then call the method corresponding to a specific end point, passing it the IP address.
- MaxMind, GeoIP, minFraud, and related trademarks belong to MaxMind, Inc.
Add the following to your build.gradle file:
JAR Files
If you are unable to use Maven or Gradle, you may include the geoip2.jarfile and its dependencies in your classpath. Download the JAR files from theGitHub Releases page.
IP Geolocation Usage
IP geolocation is inherently imprecise. Locations are often near the center ofthe population. Any location provided by a GeoIP2 database or web serviceshould not be used to identify a particular address or household.
Web Service Usage
To use the web service API, you must create a new WebServiceClient using theWebServiceClient.Builder. You must provide the Builder constructor yourMaxMind accountId and licenseKey. You may also set a timeout, specify aspecific host, or set the locales fallback order using the methods on theBuilder. After you have created the WebServiceClient, you may then callthe method corresponding to a specific end point, passing it the IP addressyou want to look up.
If the request succeeds, the method call will return a model class for the endpoint you called. This model in turn contains multiple record classes, each ofwhich represents part of the data returned by the web service.
If the request fails, the client class throws an exception.
The WebServiceClient object is safe to share across threads. If you aremaking multiple requests, the object should be reused so that new connectionsare not created for each request. Once you have finished making requests, youshould close the object to ensure the connections are closed and anyresources are promptly returned to the system.
See the API documentation for more details.
Web Service Example
Country Service
City Service
Insights Service
Database Usage
To use the database API, you must create a new DatabaseReader using theDatabaseReader.Builder. You must provide the Builder constructor either anInputStream or File for your GeoIP2 database. You may also specify thefileMode and the locales fallback order using the methods on the Builderobject.
After you have created the DatabaseReader, you may then call one of theappropriate methods, e.g., city or tryCity, for your database. Thesemethods take the IP address to be looked up. The methods with the tryprefix return an Optional object, which will be empty if the value isnot present in the database. The method without the prefix will throw anAddressNotFoundException if the address is not in the database. If youare looking up many IPs that are not contained in the database, the trymethod will be slightly faster as they do not need to construct and throwan exception. These methods otherwise behave the same.
If the lookup succeeds, the method call will return a response class for theGeoIP2 lookup. The class in turn contains multiple record classes, each ofwhich represents part of the data returned by the database.
We recommend reusing the DatabaseReader object rather than creating a newone for each lookup. The creation of this object is relatively expensive as itmust read in metadata for the file. It is safe to share the object acrossthreads.
See the API documentation for more details.
Caching
The database API supports pluggable caching (by default, no caching isperformed). A simple implementation is provided by com.maxmind.db.CHMCache.Using this cache, lookup performance is significantly improved at the cost ofa small (~2MB) memory overhead.
Usage:
Packaging Database in a JAR
If you are packaging the database file as a resource in a JAR file usingMaven, you mustdisable binary file filtering.Failure to do so will result in InvalidDatabaseException exceptions beingthrown when querying the database.
Database Example
City
Anonymous IP
ASN
Connection-Type
Maxmind What's My Ip
Domain
Enterprise
ISP
Exceptions
For details on the possible errors returned by the web service itself, seethe GeoIP2 Precision web servicedocumentation.
If the web service returns an explicit error document, this is thrown as anAddressNotFoundException, an AuthenticationException, anInvalidRequestException, or an OutOfQueriesException.
If some sort of transport error occurs, an HttpException is thrown. Thisis thrown when some sort of unanticipated error occurs, such as the webservice returning a 500 or an invalid error document. If the web servicerequest returns any status code besides 200, 4xx, or 5xx, this also becomesan HttpException.
Finally, if the web service returns a 200 but the body is invalid, the clientthrows a GeoIp2Exception. This exception also is the parent exception tothe above exceptions.
Values to use for Database or Map Keys
We strongly discourage you from using a value from any getNames method asa key in a database or map.
These names may change between releases. Instead we recommend using one of thefollowing:
com.maxmind.geoip2.record.City-City.getGeoNameIdcom.maxmind.geoip2.record.Continent-Continent.getCodeorContinent.getGeoNameIdcom.maxmind.geoip2.record.Countryandcom.maxmind.geoip2.record.RepresentedCountry-Country.getIsoCodeorCountry.getGeoNameIdcom.maxmind.geoip2.record.Subdivision-Subdivision.getIsoCodeorSubdivision.getGeoNameId
Multi-Threaded Use
This API fully supports use in multi-threaded applications. When using theDatabaseReader or the WebServiceClient in a multi-threaded application,we suggest creating one object and sharing that across threads.
What data is returned?
While many of the end points return the same basic records, the attributeswhich can be populated vary between end points. In addition, while an endpoint may offer a particular piece of data, MaxMind does not always have everypiece of data for any given IP address.
Because of these factors, it is possible for any end point to return a recordwhere some or all of the attributes are unpopulated.
See our web-service developerdocumentation fordetails on what data each end point may return.
The only piece of data which is always returned is the ip_addressavailable at lookup.getTraits().getIpAddress().
Integration with GeoNames
GeoNames offers web services and downloadabledatabases with data on geographical features around the world, includingpopulated places. They offer both free and paid premium data. Eachfeature is uniquely identified by a geonameId, which is an integer.
Many of the records returned by the GeoIP2 web services and databasesinclude a getGeoNameId() method. This is the ID of a geographicalfeature (city, region, country, etc.) in the GeoNames database.
Some of the data that MaxMind provides is also sourced from GeoNames. Wesource things like place names, ISO codes, and other similar data fromthe GeoNames premium data set.
Reporting data problems
If the problem you find is that an IP address is incorrectly mapped,pleasesubmit your correction to MaxMind.
If you find some other sort of mistake, like an incorrect spelling,please check the GeoNames site first. Onceyou've searched for a place and found it on the GeoNames map view, thereare a number of links you can use to correct data ('move', 'edit','alternate names', etc.). Once the correction is part of the GeoNamesdata set, it will be automatically incorporated into future MaxMindreleases.
If you are a paying MaxMind customer and you're not sure where to submita correction, please [contact MaxMind support](https://www.maxmind.com/en/support) for help.
Other Support
Please report all issues with this code using theGitHub issue tracker.
If you are having an issue with a MaxMind service that is not specificto the client API, pleasecontact MaxMind support.
Requirements
Maxmind My Ipod
MaxMind has tested this API with Java 8 and above.
Integration with GeoNames
GeoNames offers web services and downloadabledatabases with data on geographical features around the world, includingpopulated places. They offer both free and paid premium data. Eachfeature is uniquely identified by a geonameId, which is an integer.
Many of the records returned by the GeoIP2 web services and databasesinclude a getGeoNameId() method. This is the ID of a geographicalfeature (city, region, country, etc.) in the GeoNames database.
Some of the data that MaxMind provides is also sourced from GeoNames. Wesource things like place names, ISO codes, and other similar data fromthe GeoNames premium data set.
Reporting data problems
If the problem you find is that an IP address is incorrectly mapped,pleasesubmit your correction to MaxMind.
If you find some other sort of mistake, like an incorrect spelling,please check the GeoNames site first. Onceyou've searched for a place and found it on the GeoNames map view, thereare a number of links you can use to correct data ('move', 'edit','alternate names', etc.). Once the correction is part of the GeoNamesdata set, it will be automatically incorporated into future MaxMindreleases.
If you are a paying MaxMind customer and you're not sure where to submita correction, please [contact MaxMind support](https://www.maxmind.com/en/support) for help.
Other Support
Please report all issues with this code using theGitHub issue tracker.
If you are having an issue with a MaxMind service that is not specificto the client API, pleasecontact MaxMind support.
Requirements
Maxmind My Ipod
MaxMind has tested this API with Java 8 and above.
Contributing
Patches and pull requests are encouraged. Please include unit testswhenever possible.
Versioning
The GeoIP2 Java API uses Semantic Versioning.
Copyright and License
Maxmind Geoip2
This software is Copyright (c) 2013-2020 by MaxMind, Inc.
Maxmind Locate My Ip
This is free software, licensed under the Apache License, Version 2.0.
