Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork0
Python code for GeoIP2 webservice client and database reader
License
akx/GeoIP2-python
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This package provides an API for the GeoIP2 and GeoLite2web services anddatabases.
To install thegeoip2 module, type:
$ pip install geoip2$ pip install geoip2[aiohttp]# Install aiohttp as well$ pip install geoip2[requests]# Install requests as well
If you are not able to install from PyPI, you may also usepip from thesource directory:
$ python -m pip install.If you wish to use the C extension for the database reader, you must firstinstall thelibmaxminddb C API.Pleasesee the instructions distributed with it.
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.
To use this API, you first construct either ageoip2.webservice.Client orgeoip2.webservice.AsyncClient, passing your MaxMindaccount_id andlicense_key to the constructor. To use the GeoLite2 web service instead ofthe GeoIP2 web service, set the optionalhost keyword argument togeolite.info. To use the Sandbox GeoIP2 web service instead of theproduction GeoIP2 web service, set the optionalhost keyword argument tosandbox.maxmind.com.
After doing this, you may call the method corresponding to request type(e.g.,city orcountry), passing it the IP address you want to look up.
If the request succeeds, the method call will return a model class for theendpoint 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.
>>>import geoip2.webservice>>>>>># This creates a Client object that can be reused across requests.>>># Replace "42" with your account ID and "license_key" with your license>>># key. Set the "host" keyword argument to "geolite.info" to use the>>># GeoLite2 web service instead of the GeoIP2 web service. Set the>>># "host" keyword argument to "sandbox.maxmind.com" to use the Sandbox>>># GeoIP2 web service instead of the production GeoIP2 web service.>>>with geoip2.webservice.Client(42,'license_key')as client:>>>>>># Replace "city" with the method corresponding to the web service>>># that you are using, i.e., "country", "city", or "insights". Please>>># note that Insights is not supported by the GeoLite2 web service.>>> response= client.city('203.0.113.0')>>>>>> response.country.iso_code'US'>>> response.country.name'United States'>>> response.country.names['zh-CN']u'美国'>>>>>> response.subdivisions.most_specific.name'Minnesota'>>> response.subdivisions.most_specific.iso_code'MN'>>>>>> response.city.name'Minneapolis'>>>>>> response.postal.code'55455'>>>>>> response.location.latitude44.9733>>> response.location.longitude-93.2323>>>>>> response.traits.networkIPv4Network('203.0.113.0/32')
>>>import asyncio>>>>>>import geoip2.webservice>>>>>>asyncdefmain():>>># This creates an AsyncClient object that can be reused across>>># requests on the running event loop. If you are using multiple event>>># loops, you must ensure the object is not used on another loop.>>>#>>># Replace "42" with your account ID and "license_key" with your license>>># key. Set the "host" keyword argument to "geolite.info" to use the>>># GeoLite2 web service instead of the GeoIP2 web service. Set the>>># "host" keyword argument to "sandbox.maxmind.com" to use the Sandbox>>># GeoIP2 web service instead of the production GeoIP2 web service.>>>asyncwith geoip2.webservice.AsyncClient(42,'license_key')as client:>>>>>># Replace "city" with the method corresponding to the web service>>># that you are using, i.e., "country", "city", or "insights". Please>>># note that Insights is not supported by the GeoLite2 web service.>>> response=await client.city('203.0.113.0')>>>>>> response.country.iso_code'US'>>> response.country.name'United States'>>> response.country.names['zh-CN']u'美国'>>>>>> response.subdivisions.most_specific.name'Minnesota'>>> response.subdivisions.most_specific.iso_code'MN'>>>>>> response.city.name'Minneapolis'>>>>>> response.postal.code'55455'>>>>>> response.location.latitude44.9733>>> response.location.longitude-93.2323>>>>>> response.traits.networkIPv4Network('203.0.113.0/32')>>>>>> asyncio.run(main())
For details on the possible errors returned by the web service itself, seehttps://dev.maxmind.com/geoip/docs/web-services?lang=en for the GeoIP2 webservice docs.
If the web service returns an explicit error document, this is thrown as aAddressNotFoundError,AuthenticationError,InvalidRequestError, orOutOfQueriesError as appropriate. These all subclassGeoIP2Error.
If some other sort of error occurs, this is thrown as anHTTPError. Thisis thrown when some sort of unanticipated error occurs, such as the webservice returning a 500 or an invalid error document. If the web servicereturns any status code besides 200, 4xx, or 5xx, this also becomes anHTTPError.
Finally, if the web service returns a 200 but the body is invalid, the clientthrows aGeoIP2Error.
To use the database API, you first construct ageoip2.database.Reader usingthe path to the file as the first argument. After doing this, you may call themethod corresponding to database type (e.g.,city orcountry), passing itthe IP address you want to look up.
If the lookup succeeds, the method call will return a model class for thedatabase method you called. This model in turn contains multiple record classes,each of which represents part of the data for the record.
If the request fails, the reader class throws an exception.
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoLite2-City.mmdb')as reader:>>>>>># Replace "city" with the method corresponding to the database>>># that you are using, e.g., "country".>>> response= reader.city('203.0.113.0')>>>>>> response.country.iso_code'US'>>> response.country.name'United States'>>> response.country.names['zh-CN']u'美国'>>>>>> response.subdivisions.most_specific.name'Minnesota'>>> response.subdivisions.most_specific.iso_code'MN'>>>>>> response.city.name'Minneapolis'>>>>>> response.postal.code'55455'>>>>>> response.location.latitude44.9733>>> response.location.longitude-93.2323>>>>>> response.traits.networkIPv4Network('203.0.113.0/24')
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoIP2-Anonymous-IP.mmdb')as reader:>>>>>> response= reader.anonymous_ip('203.0.113.0')>>>>>> response.is_anonymousTrue>>> response.is_anonymous_vpnFalse>>> response.is_hosting_providerFalse>>> response.is_public_proxyFalse>>> response.is_residential_proxyFalse>>> response.is_tor_exit_nodeTrue>>> response.ip_address'203.0.113.0'>>> response.networkIPv4Network('203.0.113.0/24')
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoIP-Anonymous-Plus.mmdb')as reader:>>>>>> response= reader.anonymous_plus('203.0.113.0')>>>>>> response.anonymizer_confidence30>>> response.is_anonymousTrue>>> response.is_anonymous_vpnTrue>>> response.is_hosting_providerFalse>>> response.is_public_proxyFalse>>> response.is_residential_proxyFalse>>> response.is_tor_exit_nodeFalse>>> response.ip_address'203.0.113.0'>>> response.networkIPv4Network('203.0.113.0/24')>>> response.network_last_seendatetime.date(2025, 4, 18)>>> response.provider_nameFooBar VPNs
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoLite2-ASN.mmdb')as reader:>>> response= reader.asn('203.0.113.0')>>> response.autonomous_system_number1221>>> response.autonomous_system_organization'Telstra Pty Ltd'>>> response.ip_address'203.0.113.0'>>> response.networkIPv4Network('203.0.113.0/24')
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoIP2-Connection-Type.mmdb')as reader:>>> response= reader.connection_type('203.0.113.0')>>> response.connection_type'Corporate'>>> response.ip_address'203.0.113.0'>>> response.networkIPv4Network('203.0.113.0/24')
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoIP2-Domain.mmdb')as reader:>>> response= reader.domain('203.0.113.0')>>> response.domain'umn.edu'>>> response.ip_address'203.0.113.0'
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoIP2-Enterprise.mmdb')as reader:>>>>>># Use the .enterprise method to do a lookup in the Enterprise database>>> response= reader.enterprise('203.0.113.0')>>>>>> response.country.confidence99>>> response.country.iso_code'US'>>> response.country.name'United States'>>> response.country.names['zh-CN']u'美国'>>>>>> response.subdivisions.most_specific.name'Minnesota'>>> response.subdivisions.most_specific.iso_code'MN'>>> response.subdivisions.most_specific.confidence77>>>>>> response.city.name'Minneapolis'>>> response.country.confidence11>>>>>> response.postal.code'55455'>>>>>> response.location.accuracy_radius50>>> response.location.latitude44.9733>>> response.location.longitude-93.2323>>>>>> response.traits.networkIPv4Network('203.0.113.0/24')
>>>import geoip2.database>>>>>># This creates a Reader object. You should use the same object>>># across multiple requests as creation of it is expensive.>>>with geoip2.database.Reader('/path/to/GeoIP2-ISP.mmdb')as reader:>>> response= reader.isp('203.0.113.0')>>> response.autonomous_system_number1221>>> response.autonomous_system_organization'Telstra Pty Ltd'>>> response.isp'Telstra Internet'>>> response.organization'Telstra Internet'>>> response.ip_address'203.0.113.0'>>> response.networkIPv4Network('203.0.113.0/24')
If the database file does not exist or is not readable, the constructor willraise aFileNotFoundError or aPermissionError. If the IP address passedto a method is invalid, aValueError will be raised. If the file is invalidor there is a bug in the reader, amaxminddb.InvalidDatabaseError will beraised with a description of the problem. If an IP address is not in thedatabase, aAddressNotFoundError will be raised.
AddressNotFoundError references the largest subnet where no address would befound. This can be used to efficiently enumerate entire subnets:
importgeoip2.databaseimportgeoip2.errorsimportipaddress# This creates a Reader object. You should use the same object# across multiple requests as creation of it is expensive.withgeoip2.database.Reader('/path/to/GeoLite2-ASN.mmdb')asreader:network=ipaddress.ip_network("192.128.0.0/15")ip_address=network[0]whileip_addressinnetwork:try:response=reader.asn(ip_address)response_network=response.networkexceptgeoip2.errors.AddressNotFoundErrorase:response=Noneresponse_network=e.networkprint(f"{response_network}:{response!r}")ip_address=response_network[-1]+1# move to next subnet
We strongly discourage you from using a value from any ``names`` property asa key in a database or dictionaries.
These names may change between releases. Instead we recommend using one of thefollowing:
geoip2.records.City-city.geoname_idgeoip2.records.Continent-continent.codeorcontinent.geoname_idgeoip2.records.Countryandgeoip2.records.RepresentedCountry-country.iso_codeorcountry.geoname_idgeoip2.records.subdivision-subdivision.iso_codeorsubdivision.geoname_id
While many of the models contain the same basic records, the attributes whichcan be populated vary between web service endpoints or databases. Inaddition, while a model may offer a particular piece of data, MaxMind does notalways have every piece of data for any given IP address.
Because of these factors, it is possible for any request to return a recordwhere some or all of the attributes are unpopulated.
The only piece of data which is always returned is theip_addressattribute in thegeoip2.records.Traits record.
GeoNames offers web services and downloadabledatabases with data on geographical features around the world, includingpopulated places. They offer both free and paid premium data. Each feature isuniquely identified by ageoname_id, which is an integer.
Many of the records returned by the GeoIP web services and databases include ageoname_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. Wesource things like place names, ISO codes, and other similar data from theGeoNames premium data set.
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, pleasecheck theGeoNames site first. Once you'vesearched for a place and found it on the GeoNames map view, there are anumber of links you can use to correct data ("move", "edit", "alternatenames", etc.). Once the correction is part of the GeoNames data set, itwill be automatically incorporated into future MaxMind releases.
If you are a paying MaxMind customer and you're not sure where to submit acorrection, pleasecontact MaxMind support for help.
Python 3.9 or greater is required. Older versions are not supported.
The Requests HTTP library is also required. See<https://pypi.org/project/requests/> for details.
The GeoIP2 Python API usesSemantic Versioning.
Please report all issues with this code using theGitHub issue tracker
If you are having an issue with a MaxMind service that is not specific to theclient API, please contactMaxMind support for assistance.
About
Python code for GeoIP2 webservice client and database reader
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
Packages0
Languages
- Python99.0%
- Shell1.0%