Maxmind Geoip Database Format Bibliography

I use GeoIP fairly regularly. How I would set this up:

- Free version: only updated once [every 6 months / a year] and non-commercial use only

- Paid version: $9.99 for a year of free updates

- Updates come both in diff and in full version (for the commercial version)

- Use a common format, or use multiple formats. People love csv, but more serious applications probably use an existing format (I see maxmind a lot in this thread).

- Perhaps an API with heavy ratelimiting for people who need only a very occasional lookup (for very occasional use, I use ip2location.com/demo currently; for more serious stuff I download a database).

Having a free version with a nice license might also get you included in a lot of open source software, which increases name visibility and makes people write parsers for your format of choice.

A minor note on payment: accept Paypal and/or Bitcoin, or I (and many other Europeans) can never pay you. These credit card-only services are impossible to order from.

Idea for the diff: if you have a binary format, perhaps use this: https://www.chromium.org/developers/design-documents/softwar...

In addition to our MaxMind DB binary format, we also offer GeoIP2 databases in a CSV format suitable for importing into a SQL database. This documentation details the format of those CSV files. The CSV files are shipped as a single zip file.

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.

Zip File

The zip file itself is named . The is either “GeoIP2” or “GeoLite2”. The refers to the particular product name, such as “City” or “Country”. For the city subset by continent databases, the is one of “City-Africa”, “City-Asia-Pacific”, “City-Europe”, “City-North-America”, or “City-South-America”.

The downloaded zip file contains a single directory which in turn contains four files. That directory is named . The files are , , , and .

CSV File Format

All the CSV files start with a single header row containing column names. The specific column names and their contents are detailed below. The files are encoded as UTF-8.

Blocks Files

There are two CSV files for network blocks, one each for IPv4 and IPv6 blocks. These files are named and 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.

Included in …
NameTypeDescriptionCountry?City?
networkIP 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.
geoname_idinteger 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.
registered_country_geoname_idinteger 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.
represented_country_geoname_idinteger 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 registered country as specified by GeoNames. This ID can be used to look up the location information in the Location file.
is_anonymous_proxybooleanDeprecated. Please see our GeoIP2 Anonymous IP database to determine whether the IP address is used by an anonymizing service.
is_satellite_providerbooleanDeprecated. Please see our GeoIP2 Anonymous IP database.
postal_codestring The postal code associated with the IP address. These are available for some IP addresses in Australia, Canada, France, Germany, Italy, Spain, Switzerland, United Kingdom, and the US. We return the first 3 characters for Canadian postal codes. We return the the first 2-4 characters (outward code) for postal codes in the United Kingdom.
latitude*decimal The approximate latitude of the postal code, city, subdivision or country associated with the IP address.
longitude*decimal The approximate longitude of the postal code, city, subdivision or country associated with the IP address.
accuracy_radiusinteger The approximate accuracy radius, in kilometers, around the latitude and longitude for the geographical entity (country, subdivision, city or postal code) associated with the IP address. We have a 67% confidence that the location of the end-user falls within the area defined by the accuracy radius and the latitude and longitude coordinates.
* The coordinates are not precise and should not be used to identify a particular street address or household. To better represent a level of accuracy, please include the 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. The other possible locales are “de”, “es”, “fr”, “ja”, “pt-BR”, “ru”, and “zh-CN”. Depending on the data available for a given GeoIP2 data set, we may not include all of these locales.

These files are named . An example name would be “GeoIP2-City-Locations-en.csv”.

City subset by continent databases locations files have the same columns as the City database.

Included in …
NameTypeDescriptionCountry?City?
geoname_idinteger A unique identifier for the a location as specified by GeoNames. This ID can be used as a key for the Location file.
locale_codestring The locale that the names in this row are in. This will always correspond to the locale name of the file.
continent_codestring (2)

The continent code for this location. Possible codes are:

  • AF – Africa
  • AN – Antarctica
  • AS – Asia
  • EU – Europe
  • NA – North America
  • OC – Oceania
  • SA – South America
continent_namestring The continent name for this location in the file’s locale.
country_iso_codestring (2) A two-character ISO 3166-1 country code for the country associated with the location.
country_namestring The country name for this location in the file’s locale.
subdivision_1_iso_codestring (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_namestring 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.
subdivision_2_iso_codestring (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_namestring 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.
city_namestring The city name for this location in the file’s locale.
metro_codeinteger The metro code associated with the location. These are only available for networks in the US. MaxMind provides the same metro codes as used by DoubleClick.
time_zonestring The time zone associated with location, as specified by the IANA Time Zone Database, e.g., “America/New_York”.
is_in_european_unionboolean This is if the country associated with the location is a member state of the European Union. It is otherwise.

Returned Values as Database, Map, Dict, or Hash Keys

We strongly discourage you from using a value from any 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 objectRecommended key
city
continent
country
postal
subdivisions

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.

0 Thoughts to “Maxmind Geoip Database Format Bibliography

Leave a comment

L'indirizzo email non verrà pubblicato. I campi obbligatori sono contrassegnati *