GeoIP2 Precision Web Services

If you are a legacy GeoIP customer, please see our “What’s New in GeoIP2” document for a general overview of the changes from legacy GeoIP to GeoIP2.

Client APIs

MaxMind APIs

If you are using one of the languages listed in the table below, we strongly encourage you to use the officially supported library. There will be no need to interface with the REST API directly.

Language or Framework	Package Repository	Documentation	Version Control
.NET (C#)	NuGet	GitHub Pages	GitHub
Java	Maven Central Repository	GitHub Pages	GitHub
JavaScript (browser)		API Docs
Perl	CPAN	MetaCPAN	GitHub
PHP	Packagist	GitHub Pages	GitHub
Python	PyPI	Read the Docs	GitHub

Third-Party APIs

Language or Framework	API Name	Package Repository	Documentation	Version Control
Go	geoip2		GoDoc	GitHub
Node.js	geoip2ws	npm	npm	GitHub
Ruby	Geoip2	RubyGems.org	RubyDoc.info	GitHub

Per-Service URIs

The URI for each service is as specified below. Please replace {ip_address} with the address you are querying. All API calls should be made with HTTP GET.

Service	URI	Content-Type
Country	https://geoip.maxmind.com/geoip/v2.1/country/{ip_address}	application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1
City	https://geoip.maxmind.com/geoip/v2.1/city/{ip_address}	application/vnd.maxmind.com-city+json; charset=UTF-8; version=2.1
Insights	https://geoip.maxmind.com/geoip/v2.1/insights/{ip_address}	application/vnd.maxmind.com-insights+json; charset=UTF-8; version=2.1

IP Address

The IP address can be either an IPv4 or an IPv6 address. IPv4 addresses should be passed in the standard dotted quad form, for example 1.2.3.4. IPv6 addresses should be passed as strings as well. We recommend using the canonical form as described in RFC 5952, for example 2001:db8::1:0:0:1, but we will handle any valid IPv6 string representation.

You can also use the string me as the IP address. In this case, the record for the IP address you are querying from will be returned. This is useful when your application does not have easy access to its public IP address, e.g., when the system making the query is behind a NAT.

Request Headers

The Accept header for a request is entirely optional. If you do include one, you must accept one of the following:

• application/json
• application/vnd.maxmind.com-country+json
• application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1

Substitute the appropriate service’s type for “country”. A request for any other MIME type will result in a 415 Unsupported Media Type error.

If you set the Accept-Charset header in your client code, you must accept the UTF-8 character set. If you don’t you will receive a 406 Not Acceptable response, because this data is only available in UTF-8.

Authorization

The HTTP Authorization header is required for authorization. The username is your MaxMind user ID. The password is your MaxMind license key. You must request a trial account or subscribe to one of our web services in order to receive a user ID and license key.

We use basic HTTP authentication, but APIs which require authentication are only available via HTTPS, so credentials are never transmitted unencrypted. If you attempt to access this service via HTTP, you will receive a 403 Forbidden HTTP response.

Response Headers

The Content-Type header for a successful response varies based on the service you are using.

Errors may be returned with the Content-Type set to application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.1. If this is the case, then the body of the response contains a JSON document with two keys, code and error. See the Errors section for more details.

The response will always include a Content-Length header as well.

Response Body

All services return data as a JSON document. The document that is returned always consists of an object (aka map or hash). Each key in the object in turn maps to an object or an array of objects. The top-level structure of a document will look something like this:

The exact set of top-level keys varies based on the particular GeoIP2 Precision service you are using. If a key maps to an undefined or empty value, it is not included in the JSON object. This applies both to top-level keys and the objects they map to.

The data returned in the document will be in UTF-8 encoding.

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.

Languages

Many of the objects listed below include a names key. The value of that key is in turn an object which maps locale codes to a name in the appropriate language and script.

Currently, this web service may return the following locale codes:

Code	Language	Notes
de	German
en	English	English names may still include accented characters if that is the accepted spelling in English. In other words, English does not mean ASCII.
es	Spanish
fr	French
ja	Japanese
pt-BR	Brazilian Portuguese
ru	Russian
zh-CN	Chinese (Simplified)

If an object has any name data, then en will be one of the keys in the names object. No other language is guaranteed. However, it possible that we might not have any name data at all for a given object.

city

A JSON object containing details about the city associated with the IP address.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
confidence	integer	A value from 0-100 representing our confidence that the city is correct.
geoname_id	integer	A unique identifier for the city as specified by GeoNames.
names	JSON object (map)	A map from locale codes, such as en, to the localized names for the feature.

continent

A JSON object containing information about the continent associated with the IP address.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
code	string (2)	A two-character code for the continent associated with the IP address. The possible codes are: AF – Africa AN – Antarctica AS – Asia EU – Europe NA – North America OC – Oceania SA – South America
geoname_id	integer	A unique identifier for the continent as specified by GeoNames.
names	JSON object (map)	A map from locale codes, such as en, to the localized names for the feature.

country

A JSON object containing details about the country where MaxMind believes the end user is located.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
confidence	integer	A value from 0-100 representing our confidence that the country is correct.
iso_code	string (2)	A two-character ISO 3166-1 country code for the country associated with the IP address.
geoname_id	integer	A unique identifier for the country as specified by GeoNames.
names	JSON object (map)	A map from locale codes, such as en, to the localized names for the feature.

location

A JSON object containing specific details about the location associated with the IP address.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
accuracy_radius	integer	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.
average_income	integer	The average annual income associated with the IP address in US dollars.
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.*
metro_code	integer	The metro code associated with the IP address. These are only available for IP addresses in the US. MaxMind returns the same metro codes as used by DoubleClick.
population_density	integer	The estimated number of people per square kilometer.
time_zone	string	The time zone associated with location, as specified by the IANA Time Zone Database, e.g., “America/New_York”.

* 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.

postal

A JSON object containing details about the postal code associated with the IP address.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
code	string	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.
confidence	integer	A value from 0-100 representing our confidence that the postal code is correct.

registered_country

A JSON object containing details about the country in which the ISP has registered the IP address.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
iso_code	string (2)	A two-character ISO 3166-1 country code for the country associated with the IP address.
geoname_id	integer	A unique identifier for the country as specified by GeoNames.
names	JSON object (map)	A map from locale codes, such as en, to the localized names for the feature.

represented_country

A JSON object containing details about the country which is represented by users of the IP address. For instance, the country represented by an overseas military base.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
iso_code	string (2)	A two-character ISO 3166-1 country code for the country associated with the IP address.
geoname_id	integer	A unique identifier for the country as specified by GeoNames.
names	JSON object (map)	A map from locale codes, such as en, to the localized names for the feature.
type	string	The type of represented country. Currently limited to military but may include other types in the future.

subdivisions

A array of JSON objects. Each of these objects contains details about a subdivision of the country in which the IP address resides. Subdivisions are arranged from largest to smallest.

For instance, the response for Oxford in the United Kingdom would have an object for England as the first element in subdivisions array and an object for Oxfordshire as the second element. The subdivisions array for Minneapolis in the United States will have a single object for Minnesota.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
confidence	integer	A value from 0-100 representing our confidence that the region is correct.
geoname_id	integer	A unique identifier for the region as specified by GeoNames.
iso_code	string	A string of up to three characters containing the region-portion of the ISO 3166-2 code for the region associated with the IP address.
names	JSON object (map)	A map from locale codes, such as en, to the localized names for the feature.

traits

A JSON object containing general traits associated with the IP address.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
autonomous_system_number	integer	The autonomous system number associated with the IP address.
autonomous_system_organization	string	The organization associated with the registered autonomous system number for the IP address.
domain	string	The second level domain associated with the IP address. This will be something like “example.com” or “example.co.uk”, not “foo.example.com”.
ip_address	string	The requested IP address.
is_anonymous_proxy	boolean	Deprecated. Please see our GeoIP2 Anonymous IP database to determine whether the IP address is used by an anonymizing service.
is_satellite_provider	boolean	Deprecated.
isp	string	The name of the ISP associated with the IP address.
organization	string	The name of the organization associated with the IP address.
user_type	string	The user type associated with the IP address. This will be one of the following values. business cafe cellular college content_delivery_network dialup government hosting library military residential router school search_engine_spider traveler

maxmind

A JSON object containing information related to your MaxMind account.

			Included in …
Key	Value Type	Description	Country?	City?	Insights?
queries_remaining	integer	The approximate number of remaining queries available for the end point which is being called.

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

We strongly discourage your from using a value from any names 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	code or geoname_id
country, registered_country, and represented_country	iso_code or geoname_id
postal	code
subdivisions	iso_code or geoname_id

Output Examples

Below is an Insights output example containing all of the possible fields.

Command Line (curl) Example

The web service may be accessed using curl, a simple command-line HTTP client. The -u flag is used to pass the HTTP basic authentication header that provides the web service with your credentials.

Errors

When the server returns an error (4xx or 5xx), the response may include a JSON document in the body. This document is a single object with the keys code and error. The code field is a static error code for machine use. The value of any given code will never change, though codes can be added or removed. The error field is a human-readable description of the error and may change at any time.

Not all errors include a JSON body. An error in content negotiation will not include a body, nor will many 5xx errors, which typically happen outside of our web service request handling code. You should check the Content-Type type of an error response before attempting to decode the body as JSON.

In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.

Code	HTTP Status	Description
IP_ADDRESS_INVALID	400 Bad Request	You have not supplied a valid IPv4 or IPv6 address.
IP_ADDRESS_REQUIRED	400 Bad Request	You have not supplied an IP address, which is a required field.
IP_ADDRESS_RESERVED	400 Bad Request	You have supplied an IP address which belongs to a reserved or private range.
IP_ADDRESS_NOT_FOUND	404 Not Found	The supplied IP address is not in the database.
AUTHORIZATION_INVALID	401 Unauthorized	You have supplied an invalid MaxMind user ID and/or license key in the Authorization header.
LICENSE_KEY_REQUIRED	401 Unauthorized	You have not supplied a MaxMind license key in the Authorization header.
USER_ID_REQUIRED	401 Unauthorized	You have not supplied a MaxMind user ID in the Authorization header.
OUT_OF_QUERIES	402 Payment Required	The license key you have provided is out of queries. Please purchase more queries to use this service.
PERMISSION_REQUIRED	403 Forbidden	You do not have permission to use the service. Please contact support@maxmind.com for more information.
(none)	415 Unsupported Media Type	Your request included a Content-Type header that is not supported. For GET requests, this means the web service cannot return content of that type. For PUT and POST queries, this means the web service cannot parse a request body of that type.
(none)	503 Service Not Available	There is a problem with the web service server. You can try this request again later.

Release Notes

Changes to the GeoIP2 Precision web services are documented in our release notes.

Versioning

The GeoIP2 Precision web services use two part versions. Our current release is version 2.1. The major version number will remain at 2 for the foreseeable future and will not change unless we are releasing an entirely new product (“GeoIP3”).

The minor version will only change if there are breaking changes in the web service. A breaking change is one that breaks client code that follows the documentation on this page. Breaking changes include changing the type of an existing field, deleting a field entirely, or changing URIs.

All changes to the web services will be documented in the GeoIP2 release notes, whether or not the version number is changed.

The following changes are not considered to be breaking changes and will not be accompanied by a version number change:

• Adding a new field, either at the top level of the structure or in one particular object such as the country or city. Client code should be written to allow for new fields to appear.
• Adding new values to enum fields such as user_type. Note that this also applies to fields such as country codes, country subdivision codes, time zones, etc.
• Adding a new language for localized names. We may add additional locale codes in the future.
• Adding or removing error codes, and/or changing the body type for an error. Client code should always check the Content-Type header for any error response. Client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.
• Adding a new service. If we add a GeoIP2 Inter-Galactic service, we will use a new path such as /geoip/v2.1/inter-galactic. This should not break any existing client code.