MaxMind's GeoIP2 web services and GeoIP2 databases are an evolution of ouroriginal GeoIP web services and databases, which we now refer to as GeoIPLegacy. 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 existingdata is represented.
Localized Data
Perhaps the biggest change is the inclusion of localized name data. The servicesupports Brazilian Portuguese (pt-BR
), English (en
), French (fr
), German(de
), Japanese (ja
), Russian (ru
), Simplified Chinese (zh-CN
), andSpanish (es
).
Whenever possible, we provide a geoname_id
for things like cities, countries,and country subdivisions. The GeoNames data setincludes 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 thecountry where the IP address is located. The registered_country
is the countryin which the IP is registered. These two may differ in some cases.
Both country
and registered_country
may include the is_in_european_union
key to indicate that the country is in the European Union.
Finally, we also include a represented_country
key for some records. This isused when the IP address belongs to something like a military base. Therepresented_country
is the country that the base represents. This can beuseful 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 areavailable. The GeoIP2 databases and services do not include FIPS 10-4 regioncodes. The GeoIP Legacy databases included ISO codes for US and Canada and FIPScodes for all other countries.
We also provide multiple levels of country subdivision data. The subdivisionsthese provide correspond to the subdivisions which have been given ISO 3166-2codes. For example, in the United States, we only provide a single level ofsubdivision data, corresponding to US states. But for the United Kingdom, we mayprovide two levels. The first level is the country (England, Scotland, Wales) orprovince (Northern Ireland). The second level may be a county, a London borough,a unitary authority, council area, etc.
We provide aCSV file which maps FIPS 10-4 region codes to their corresponding ISO 3166-2 subdivision codes.Note that codes for the US and Canada are not present since we included ISOcodes for these countries in GeoIP Legacy. Also note that the CSV file maycontain outdated ISO 3166-2 subdivision codes in addition to any up-to-datecodes that may have replaced them. This file incorporates GeoNames geographicaldata, which is made available under theCreative Commons Attribution 4.0 License.
Custom Country Codes
In the GeoIP Legacy databases, we included several country codes that don'trepresent 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 nocountry set at all. It will, however, contain a continent
object, and thatcontinent will be Asia. The time_zone
key under the location
object will beset to Australia/Perth
. For EU
, we return a similar document where thecontinent is Europe and the time_zone
is Europe/Vaduz
.
For IP addresses where we used A1
or A2
, we now set the appropriate key inthe traits
object. The A1
code corresponds to the deprecatedis_anonymous_proxy
key, while A2
corresponds to the deprecatedis_satellite_provider
key. New integrations are encouraged to useis_anonymous
, is_anonymous_vpn
, is_hosting_provider
, is_public_proxy
,is_satellite_provider
, is_tor_exit_node
, and is_residential_proxy
, allavailable in the GeoIP2 Insights web service or the GeoIP2 Anonymous IPdatabase.
User Type and Net Speed (web service only)
In the GeoIP2 web services, we have effectively merged the user type and netspeed data into the user_type
key. The cellular
net speed was alreadyincluded in the list of possible user_type
values.
We have also changed the format of the user_type
values so that they are inall lower case, with words separated by underscores (_).
Autonomous System Number
In GeoIP Legacy, this was returned as a string like "AS1239 Linkem IR WiMaxNetwork". This has been split into two keys, autonomous_system_number
, aninteger, and autonomous_system_organization
, which is a string.
Area Code
The GeoIP2 databases and services do not include area codes.
Location Information
GeoIP2 Insights includes the average income and population density for the areain which the IP address is used.
IP and Network
All GeoIP2 databases and web services provide the network of the associated datarecord in the database.
GeoIP2 Insights also includes user_count
, an estimate of the number of usersusing the IP address, and the static_ip_score
, an indicator of how static ordynamic an IP allocation is.
JavaScript API Changes
The MaxMind GeoIP2 JavaScript API provides a JavaScript interface to ourGeoIP2 web service. The API calls the web service toretrieve the location information of the user as aJavaScript object.
The API is written using theJavaScript 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 web services use HTTP basicauthentication over TLS rather than passing the license key as a queryparameter.
When an error occurs, we now return an appropriate HTTP error code instead ofsimply returning a 200 with an error in the document. We also return a JSONdocument with details about the error in most cases.
Successful responses also return a JSON document. All documents, both successfuland error, are in the form of a JSON object.
Database Changes
Downloadable databases for GeoIP2 use our newMaxMind DB format. OurGeoIP2 downloadable databases page has information onhow to use the new format.
Web Service Example
This is an example of our GeoIP2 Insights web service's return document.
Latitude and longitude are not precise and should not be used to identify aparticular street address or household. To better represent a level of accuracy,please include the accuracy_radius when displaying latitude and longitude andmake it clear that the coordinates refer to a larger geographical area insteadof a precise location.
This page was last updated on June 26, 2024.