Currently, this distribution provides an API for the GeoIP2 Precision web services (as documented at http://dev.maxmind.com/geoip/precision).
In the future, this distribution will also provide the same API for the GeoIP2 downloadable databases. These databases have not yet been released as a downloadable product.
See geoip2.webservices.Client for details on the web service client API.
GeoNames (http://www.geonames.org/) offers web services and downloadable databases with data on geographical features around the world, including populated places. They offer both free and paid premium data. Each feature is unique identified by a geoname_id, which is an integer.
Many of the records returned by the GeoIP web services and databases include a geoname_id field. This is the ID of a geographical feature (city, region, country, etc.) in the GeoNames database.
Some of the data that MaxMind provides is also sourced from GeoNames. We source things like place names, ISO codes, and other similar data from the GeoNames premium data set.
If the problem you find is that an IP address is incorrectly mapped, please submit your correction to MaxMind at http://www.maxmind.com/en/correction.
If you find some other sort of mistake, like an incorrect spelling, please check the GeoNames site (http://www.geonames.org/) first. Once you’ve searched for a place and found it on the GeoNames map view, there are a number of links you can use to correct data (“move”, “edit”, “alternate names”, etc.). Once the correction is part of the GeoNames data set, it will be automatically incorporated into future MaxMind releases.
If you are a paying MaxMind customer and you’re not sure where to submit a correction, please contact MaxMind support at http://www.maxmind.com/en/support for help.
This code requires Python 2.6+ or 3.1+. Older versions are not supported.
Please report all issues with this code using the GitHub issue tracker at https://github.com/maxmind/GeoIP2-python/issues
If you are having an issue with a MaxMind service that is not specific to the client API please see http://www.maxmind.com/en/support for details.
This class provides a client API for all the GeoIP Precision web service’s end points. The end points are Country, City, City/ISP/Org, and Omni. Each end point returns a different set of data about an IP address, with Country returning the least data and Omni the most.
Each web service end point is represented by a different model class, and these model classes in turn contain multiple Record classes. The record classes have attributes which contain data about the IP address.
If the web service does not return a particular piece of data for an IP address, the associated attribute is not populated.
The web service may not return any information for an entire record, in which case all of the attributes for that record class will be empty.
Requests to the GeoIP Precision web service are always made with SSL.
The basic API for this class is the same for all of the web service end points. First you create a web service object with your MaxMind user_id and license_key, then you call the method corresponding to a specific end point, passing it the IP address you want to look up.
If the request succeeds, the method call will return a model class for the end point you called. This model in turn contains multiple record classes, each of which represents part of the data returned by the web service.
If the request fails, the client class throws an exception.
This library works on Python 2.6+ and Python 3. It requires that the requests HTTP library is installed. See <http://python-requests.org> for details.
>>> import geoip2.webservices
>>> client = geoip2.webservices.Client(42, 'abcdef123456')
>>> omni = client.omni('24.24.24.24')
>>> country = omni.country
>>> print(country.iso_3166_alpha_2)
For details on the possible errors returned by the web service itself, see http://dev.maxmind.com/geoip/precision for the GeoIP Precision web service docs.
If the web service returns an explicit error document, this is thrown as a GeoIP2WebServiceError exception. If some other sort of error occurs, this is thrown as a GeoIP2HTTPError. The difference is that the webservice error includes an error message and error code delivered by the web service. The latter is thrown when some sort of unanticipated error occurs, such as the web service returning a 500 or an invalid error document.
If the web service returns any status code besides 200, 4xx, or 5xx, this also becomes a GeoIP2HTTPError.
Finally, if the web service returns a 200 but the body is invalid, the client throws a GeoIP2Error object.
While many of the end points return the same basic records, the attributes which can be populated vary between end points. In addition, while an end point may offer a particular piece of data, MaxMind does not always have every piece of data for any given IP address.
Because of these factors, it is possible for any end point to return a record where some or all of the attributes are unpopulated.
See http://dev.maxmind.com/geoip/precision for details on what data each end point may return.
The only piece of data which is always returned is the ip_address attribute in the geoip2.records.Traits record.
Every record class attribute has a corresponding predicate method so you can check to see if the attribute is set.
This method creates a new client object.
It accepts the following required arguments:
Parameters: |
|
---|
Go to https://www.maxmind.com/en/my_license_key to see your MaxMind User ID and license key.
The following keyword arguments are also accepted:
Parameters: |
|
---|
Details on language handling:
The order of the languages is significant. When a record class has multiple names (country, city, etc.), its name property will return the name in the first language that has one.
Note that the only language which is always present in the GeoIP2 Precision data in “en”. If you do not include this language, the name property may end up returning None even when the record hass an English name.
Currently, the valid list of language codes is:
Passing any other language code will result in an error.
This method calls the GeoIP2 Precision City endpoint.
Parameters: | ip_address – IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from will be used. |
---|---|
Returns: | geoip2.models.City object |
This method calls the GeoIP2 Precision City/ISP/Org endpoint.
Parameters: | ip_address – IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from will be used. |
---|---|
Returns: | geoip2.models.CityISPOrg object |
This method calls the GeoIP2 Country endpoint.
Parameters: | ip_address – IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from will be used. |
---|---|
Returns: | geoip2.models.Country object |
This method calls the GeoIP2 Precision Omni endpoint.
Parameters: | ip_address – IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from will be used. |
---|---|
Returns: | geoip2.models.Omni object |
These classes provide models for the data returned by the GeoIP2 Precision City end point.
The only difference between the City, City/ISP/Org, and Omni model classes is which fields in each record may be populated. See http://dev.maxmind.com/geoip/precision for more details.
Model class for the GeoIP2 Precision City end point
Variables: |
|
---|
Model class for the GeoIP2 Precision City/ISP/Org end point
Variables: |
|
---|
Model class for the GeoIP2 Precision Country end point
This class provides the following methods, each of which returns a record object.
Variables: |
|
---|
Model class for the GeoIP2 Precision Omni end point
Variables: |
|
---|
Contains data for the city record associated with an IP address
This class contains the city-level data associated with an IP address.
This record is returned by all the end points except the Country end point.
Attributes:
Variables: |
|
---|
Contains data for the continent record associated with an IP address
This class contains the continent-level data associated with an IP address.
This record is returned by all the end points.
Attributes:
Variables: |
|
---|
Contains data for the country record associated with an IP address
This class contains the country-level data associated with an IP address.
This record is returned by all the end points except the Country end point.
Attributes:
Variables: |
|
---|
Contains data for the location record associated with an IP address
This class contains the location data associated with an IP address.
This record is returned by all the end points except the Country end point.
Attributes:
Variables: |
|
---|
All records with `names` subclass PlaceRecord`
All records are subclasses of Record
Contains data for the region record associated with an IP address
This class contains the region-level data associated with an IP address.
This record is returned by all the end points except the Country end point.
Attributes:
Variables: |
|
---|
Contains data for the traits record associated with an IP address
This class contains the traits data associated with an IP address.
This record is returned by all the end points.
This class has the following attributes:
Variables: |
|
---|
There was a generic error in GeoIP2.
This class represents a generic error. It extends RuntimeError and does not add any additional attributes.
There was an error when making your HTTP request.
This class represents an HTTP transport error. It extends GeoIP2Error and adds attributes of its own.
Variables: |
|
---|
The GeoIP2 web service returned an error.
This class represents an error returned by MaxMind’s GeoIP2 Precision web service. It extends GeoIP2HTTPError.
Variables: |
|
---|
copyright: |
|
---|---|
license: | GNU Lesser General Public License v2 or later (LGPLv2+) |