What’s New in GeoIP2

MaxMind's GeoIP2 Precision services and GeoIP2 databases are an evolution of our original GeoIP web services and databases, which we now refer to as GeoIP Legacy. This document highlights the most important changes for developers.

Data Changes

GeoIP2 includes a variety of new data, as well as making changes to how existing data is represented.

Localized Data

Perhaps the biggest change is the inclusion of localized name data. The service supports Brazilian Portuguese (pt-BR), English (en), French (fr), German (de), Japanese (ja), Russian (ru), Simplified Chinese (zh-CN), and Spanish (es).

Whenever possible, we provide a geoname_id for things like cities, countries, and country subdivisions. The GeoNames data set includes a huge amount of data on geographical features.

Country, Registered Country, and Represented Country

We now distinguish between several types of country data. The country is the country where the IP address is located. The registered_country is the country in which the IP is registered. These two may differ in some cases.

Finally, we also include a represented_country key for some records. This is used when the IP address belongs to something like a military base. The represented_country is the country that the base represents. This can be useful for managing content licensing, among other uses.

ISO 3166-2, FIPS 10-4, and Country Subdivisions

We now provide the ISO 3166-2 codes for country subdivisions when they are available. The GeoIP2 databases and services do not include FIPS 10-4 region codes. The GeoIP Legacy databases included ISO codes for US and Canada and FIPS codes for all other countries.

We also provide multiple levels of country subdivision data. The subdivisions these provide correspond to the subdivisions which have been given ISO 3166-2 codes. For example, in the United States, we only provide a single level of subdivision data, corresponding to US states. But for the United Kingdom, we may provide two levels. The first level is the the country (England, Scotland, Wales) or province (Northern Ireland). The second level may be a county, a London borough, a unitary authority, council area, etc.

Custom Country Codes

In the GeoIP Legacy databases we included several country codes that don't actually represent countries. These were AP (Asia/Pacific), EU (Europe), A1 (anonymous proxy), and A2 (satellite provider).

For IP addresses where we used to use AP we now return a response with no country set at all. It will, however, contain a continent object, and that continent will be Asia. The time_zone key under the location object will be set to Australia/Perth. For EU, we return a similar document where the continent is Europe and the time_zone is Europe/Vaduz.

For IP addresses where we used A1 or A2, we now set the appropriate key in the traits object. The A1 code corresponds to the is_anonymous_proxy key, while A2 corresponds to is_satellite_provider.

User Type and Net Speed

We have effectively merged the user type and net speed data into the user_type key. The possible user_type values now include dialup. The cellular net speed was already included in the list of possible user_type values.

We have also changed the format of the user_type values so that they are in all lower case, with words separated by underscores (_).

Autonomous System Number

In GeoIP Legacy, this was returned as a string like "AS1239 Linkem IR WiMax Network". This has been split into two keys, autonomous_system_number, an integer, and autonomous_system_organization, which is a string.

Area Code

The GeoIP2 databases and services do not include area codes.

JavaScript API Changes

The MaxMind GeoIP2 JavaScript API provides a JavaScript interface to our GeoIP2 Precision web service. The API calls the web service to retrieve the location information of the user as a JavaScript object.

The API is written using the the JavaScript module pattern. Rather than injecting many global functions into the top-level execution scope, it returns a single object containing multiple functions you can call.

Web Service Changes

Our GeoIP2 web services now follow REST principles.

Unlike the GeoIP Legacy web service, the GeoIP2 Precision services use HTTP basic authentication over SSL rather than passing the license key as a query parameter.

When an error occurs, we now return an appropriate HTTP error code instead of simply returning a 200 with an error in the document. We also return a JSON document with details about the error in most cases.

Successful responses also return a JSON document. All documents, both successful and error, are in the form of a JSON object.

Database Changes

Downloadable databases for GeoIP2 use our new MaxMind DB format. Our GeoIP2 downloadable databases page has information on how to use the new format.

Web Service Example

This is an example of our GeoIP2 Precision: Insights web service's return document.