GeoIP2 and GeoLite City and Country Databases
Determine the country, subdivisions (regions), city, and postal code associated with IPv4 and IPv6 addresses worldwide.
Terms and pricing for the GeoIP2 City and GeoIP2 Country databases may be found on our product pages:
IP Geolocation Usage
IP geolocation is inherently imprecise. Locations are often near the center of the population. Any location provided by a GeoIP database should not be used to identify a particular address or household.
Data Privacy
To comply with data privacy regulations, please monitor our Do Not Sell My Personal Information Requests page (login required) for IP addresses and networks that should not be used for advertising or marketing purposes. You can automate retrieval of this list using our privacy exclusions API.
Binary Databases
Binary databases make use of the MaxMind DB file format. MaxMind provides official client APIs in the language listed below. The following client APIs are open source and licensed under the Apache License, Version 2.0.
You can also use the mmdbinspect tool (in beta), a command line interface built with Go, to look up one or more IPs from one or more MMDB databases and receive output in a parsable JSON format.
| Language or Framework | Documentation | Example |
|---|---|---|
| .NET (C#) | GitHub - Database Usage | City Example |
| Java | GitHub - Database Usage | City Example |
| Node.js | GitHub - Database Usage | City Example |
| PHP | GitHub - Database Reader | City Example |
| Python | GitHub - Database Usage | City Example |
| Ruby | GitHub - Database Reader | City Example |
CSV Databases
In addition to our MaxMind DB binary format, we also offer GeoIP2 and GeoLite2 databases in a CSV format suitable for importing into a SQL database. The CSV files are shipped as a single zip file.The zip file itself is named {GeoIP2,GeoLite2}-{City,Country}-CSV_{YYYYMMDD}.zip.
The downloaded zip file contains a single directory which in turn
contains several files. That directory is named
{GeoIP2,GeoLite2}-{City,Country}-CSV_{YYYYMMDD}.
The downloaded .zip file contains a single directory which in turn contains 13 files:
| Filename | Description |
|---|---|
COPYRIGHT.txt | Copyright statement |
LICENSE.txt | End user license |
README.txt | Information file |
{GeoIP2,GeoLite2}-{City,Country}-Blocks-IPv4.csv | CSV file containing data on IPv4 addresses |
{GeoIP2,GeoLite2}-{City,Country}-Blocks-IPv6.csv | CSV file containing data on IPv6 addresses |
{GeoIP2,GeoLite2}-{City,Country}-Locations-{locale}.csv | Eight CSV files containing data location for each locale code, where {locale} can be “de”, "en", “es”, “fr”, “ja”, “pt-BR”, “ru”, and “zh-CN” . |
Blocks Files
There are two CSV files for network blocks, one each for IPv4 and IPv6 blocks.
These files are named {GeoIP2,GeoLite2}-{City,Country}-Blocks-IPv4.csv and
{GeoIP2,GeoLite2}-{City,Country}-Blocks-IPv6.csv respectively. An example name
would be GeoIP2-City-Blocks-IPv4.csv.
City subset by continent databases blocks files have the same columns as the City database.
| Name | Type | Description | Included in... |
|---|---|---|---|
| network | IP network as a string | This is the IPv4 or IPv6 network in CIDR format such as "2.21.92.0/29" or "2001:4b0::/80". We offer a utility to convert this column to start/end IPs or start/end integers. See the conversion utility section for details. | Country City |
| geoname_id | integer | A unique identifier for the network's location as specified
by
GeoNames
. This ID can be
used to look up the location information in the Location file. Learn more about GeoNames IDs on our Knowledge Base. | Country City |
| registered_country_geoname_id | integer | The registered country is the country in which the ISP has
registered the network. This column contains a unique identifier
for the network's registered country as specified
by
GeoNames
. This ID can be
used to look up the location information in the Location file. Learn more about registered countries on our Knowledge Base. | Country City |
| represented_country_geoname_id | integer | The represented country is the country which is represented by
users of the IP address. For instance, the country represented by
an overseas military base. This column contains a unique
identifier for the network's represented country as specified
by
GeoNames
. This ID can be
used to look up the location information in the Location file. Learn more about represented countries on our Knowledge Base. | Country City |
| is_anonymous_proxy | boolean | Deprecated. Please see our GeoIP2 Anonymous IP database to determine whether the IP address is used by an anonymizing service. | Country City |
| is_satellite_provider | boolean | Deprecated. | Country City |
| postal_code | string | A postal code close to the user's location. For the following
countries, we return partial postal codes with the number of
characters indicated below:
| Country City |
| latitude* | decimal | The approximate
WGS84
latitude of the location associated with the network. Learn about the geolocation area defined by latitude, longitude, and accuracy radius, on our Knowledge Base. | Country City |
| longitude* | decimal | The approximate
WGS84
longitude of the location associated with the network. Learn about the geolocation area defined by latitude, longitude, and accuracy radius, on our Knowledge Base. | Country City |
| accuracy_radius | integer | The radius in kilometers around the specified location where the IP
address is likely to be. Learn about the geolocation area defined by latitude, longitude, and accuracy radius, on our Knowledge Base. | Country City |
| is_anycast | boolean | This is
1
if the network is an
anycast network
.This column will be empty in GeoLite2-Country and GeoLite2-City. | Country City |
accuracy_radius when displaying latitude and
longitude and make it clear that the coordinates refer to a larger
geographical area instead of a precise location.Locations Files
The zip file includes one location file for each locale code for which data is
available. There will always be an “en” file containing a record for every
geoname_id used in the blocks files. Files corresponding to other locales will
exist and have a record for a geoname_id only if data is available. The other
possible locales are “de”, “es”, “fr”, “ja”, “pt-BR”, “ru”, and “zh-CN”.
These files are named {GeoIP2,GeoLite2}-{City,Country}-Locations-{locale}.csv.
An example name would be GeoIP2-City-Locations-en.csv.
City subset by continent databases blocks files have the same columns as the City database.
| Name | Type | Description | Included in... |
|---|---|---|---|
| geoname_id | integer | A unique identifier for the a location as specified
by
GeoNames
. This ID can be
used as a key for the Location file. Learn more about GeoNames IDs on our Knowledge Base. | Country City |
| locale_code | string | The locale that the names in this row are in. This will always correspond to the locale name of the file. | Country City |
| continent_code | string (2) | The continent code for this location. Possible codes are:
| Country City |
| continent_name | string | The continent name for this location in the file's locale. Learn more about localized names on our Knowledge Base. | Country City |
| country_iso_code | string (2) | A two-character ISO 3166-1 country code for the country associated with the location. | Country City |
| country_name | string | The country name for this location in the file's locale. Learn more about localized names on our Knowledge Base. | Country City |
| subdivision_1_iso_code | string (1-3) | A string of up to three characters containing the region-portion of the ISO 3166-2 code for the first level region associated with the IP address. Some countries have two levels of subdivisions, in which case this is the least specific. For example, in the United Kingdom this will be a country like "England", not a county like "Devon". | |
| subdivision_1_name | string | The subdivision name for this location in the file's locale.
As with the subdivision code, this is the least specific
subdivision for the location. Learn more about localized names on our Knowledge Base. | |
| subdivision_2_iso_code | string (1-3) | A string of up to three characters containing the region-portion of the ISO 3166-2 code for the second level region associated with the IP address. Some countries have two levels of subdivisions, in which case this is the most specific. For example, in the United Kingdom this will be a a county like "Devon", not a country like "England". | |
| subdivision_2_name | string | The subdivision name for this location in the file's locale.
As with the subdivision code, this is the most specific subdivision
for the location. Learn more about localized names on our Knowledge Base. | |
| city_name | string | The city name for this location in the file's locale. Learn more about localized names on our Knowledge Base. | |
| metro_code | integer | Metro code is a geolocation target code from Google. | |
| time_zone | string | The time zone associated with location, as specified by the IANA Time Zone Database , e.g., “America/New_York”. | |
| is_in_european_union | boolean | This is
1
if the country associated with the location is a member
state of the European Union. It is
0
otherwise. | Country City |
Returned Values as Database, Map, Dict, or Hash Keys
We strongly discourage you from using a value from any *_name field as a key
in a database or map/dict/hash data structure.
These names may change between releases. Instead we recommend using one of the following:
| Data object | Recommended key |
|---|---|
| city | geoname_id |
| continent | continent_code |
| country | country_iso_code |
| postal | postal_code |
| subdivisions | subdivision_{1,2}_iso_code |
Conversion Utility
We’ve created a small utility program to allow you to convert a GeoIP2 CSV file’s representation of IP addresses to another format. You can choose between start/end IP addresses, with the addresses represented as strings or integers.
The program is available from our geoip2-csv-converter GitHub project releases tab.
Example Files
We maintain example files in CSV and MMDB format. The files contain dummy data rather than real GeoIP data.CSV Example Files
We maintain examples of the CSV files as they would be downloaded from the account portal:
MMDB Example Files
We maintain test MMDB files on GitHub:
Alternatively, you can view all of our MMDB test data on GitHub.
Database Sizes
MaxMind databases can vary in size from release to release. If you are working with file size limitations that are concerning, you should build your integrations to fail gracefully in event of a significant size change.
From August to October 2024, the database files varied in file size and number of networks as follows:
| Database | CSV File Size | MMDB File Size | IPv4 Networks | IPv6 Networks |
|---|---|---|---|---|
| GeoIP City | 583 MB - 637 MB | 108 MB - 113 MB | 6,360,000 - 7,260,000 | 2,580,000 - 2,970,000 |
| GeoIP Country | 30.2 MB - 35.6 MB | 6.57 MB - 7.16 MB | 482,000 - 505,000 | 284,000 - 389,000 |
| GeoLite City | 231.5 MB - 265.0 MB | 50.8 MB - 54.2 MB | 2,370,000 - 3,400,000 | 1,200,000 - 1,670,000 |
| GeoLite Country | 30.6 MB - 38.2 MB | 6.61 MB - 7.57 MB | 478,000 - 496,000 | 297,000 - 476,000 |
The listed file sizes are for unpacked databases. Databases are downloaded in a compressed format.
Database Changes
We may add new data fields to the City and Country database at any time.
New database fields are added as new columns to the right of existing columns in our CSV files, and as additional data in our MMDB files.
Subscribe to our GeoIP2 release notes to be notified when new data is added to our databases.