GeoIP and GeoLite API Responses
Headers
The Content-Type for a successful response varies based on the service as
outlined below:
| Service | Content-Type |
|---|---|
| GeoIP2 Country | application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1 |
| GeoIP2 City | application/vnd.maxmind.com-city+json; charset=UTF-8; version=2.1 |
| GeoIP2 Insights | application/vnd.maxmind.com-insights+json; charset=UTF-8; version=2.1 |
| GeoLite2 Country | application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1 |
| GeoLite2 City | application/vnd.maxmind.com-city+json; charset=UTF-8; version=2.1 |
Errors may be returned with the Content-Type set to
application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.0. 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.
Bodies
Each service returns data as a JSON document. The document that is returned always consists of an object (aka map or hash). Below are the schema definitions that describe each service's response body.
GeoIP2 Country Body Example
The following is an example of a full response to a GeoIP2 Country web service request.
A GeoLite2 Country request follow the same structure, but the data returned will
be less accurate. In addition, GeoLite Country requests will not return the
maxmind object.
GeoIP2 City Body Example
The following is an example of a full response to a GeoIP2 City Plus web service request.
A GeoLite2 City request follow the same structure, but the data returned will be
less accurate. In addition, GeoLite2 City requests will not return the domain,
isp, or organization values in the traits object, and it will not return
the maxmind object.
GeoIP2 Insights Body Example
The following is an example of a full response to a GeoIP2 Insights web service request.
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 |
|---|---|---|
| 400 Bad Request | You have not supplied a valid IPv4 or IPv6 address. |
| 400 Bad Request | You have not supplied an IP address, which is a required field. |
| 400 Bad Request | You have supplied an IP address which belongs to a reserved or private range. |
| 401 Unauthorized | You have supplied an invalid MaxMind account ID and/or license key in the Authorization header. |
| 401 Unauthorized | You have not supplied a MaxMind license key in the Authorization header. |
| 401 Unauthorized | You have not supplied a MaxMind account ID in the Authorization header. |
| 402 Payment Required | The license key you have provided does not have sufficient funds to use this service. Please purchase more service credits. |
| 402 Payment Required | You do not have permission to use the service. Please contact support@maxmind.com for more information. |
(none) | 403 Forbidden | This status is returned when the request body is larger than 20,000 bytes. |
| 404 Not Found | The supplied IP address is not in the database. |
(none) | 415 Unsupported Media Type | Your request included a |
(none) | 503 Service Not Available | There is a problem with the web service server. You can try this request again later. |
Object Reference
Each schema definition contains a description of an object, along with a list of properties that belong to the object. The following information is listed for each object property:
- name
- type (
array<type>,boolean,number,integer,object,string) - description
- example
- formatting
- constraints
- supported services (
Country,City,Insights)
Additionally, for object properties, a link is provided to view a schema
definition that further describes that specific object.
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 exact set of top-level keys varies based on the particular GeoIP2 web 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.
A JSON object containing information about the continent associated with the IP address.
A JSON object containing details about the country where MaxMind believes the end user is located.
A JSON object containing specific details about the location associated with the IP address.
A JSON object containing details about the postal code associated with the IP address.
A JSON object containing details about the country in which the ISP has registered the IP address.
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.
An 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.
A JSON object containing details about the city associated with the IP address.
A map from locale codes, such as en, to the localized names for the
feature.
Learn more about localized geolocation names on our Knowledge Base.
A JSON object containing information about the continent associated with the IP address.
A two-character code for the continent associated with the IP address. The possible codes are:
AF– AfricaAN– AntarcticaAS– AsiaEU– EuropeNA– North AmericaOC– OceaniaSA– South America
A map from locale codes, such as en, to the localized names for the
feature.
Learn more about localized geolocation names on our Knowledge Base.
A JSON object containing details about the country where MaxMind believes the end user is located.
This is true if the country is a member state of the European Union.
Otherwise, the key is not included in the country object.
Learn more about the European Union flag on our Knowledge Base.
A two-character ISO 3166-1 country code for the country associated with the IP address.
A map from locale codes, such as en, to the localized names for the
feature.
Learn more about localized geolocation names on our Knowledge Base.
A JSON object containing specific details about the location associated with the IP address.
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 average annual income associated with the IP address in US dollars. This is only available for IP addresses in the US.
The approximate WGS84 latitude of the postal code, city, subdivision or country associated with the IP address.
IP Geolocation Usage
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.
The approximate WGS84 longitude of the postal code, city, subdivision or country associated with the IP address.
IP Geolocation Usage
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.
The estimated number of people per square kilometer. This is only available for IP addresses in the US.
Learn more about population density data on our Knowledge Base.
The time zone associated with location, as specified by the IANA Time Zone Database, e.g., "America/New_York".
A JSON object containing details about the postal code associated with the IP address.
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:
United States: 5
Canada: 3
United Kingdom: 2-4
Brazil: 5
Ireland: 3
Japan: 7 (specified for the first 6. The last digit defaults to 1)
Netherlands: 4
Portugal: 7 (accurate for the first 4. The last 3 often defaults to
-001)Singapore: 2
A value from 0-100 representing our confidence that the postal code is correct.
A JSON object containing details about the country in which the ISP has registered the IP address.
Learn about registered countries on our Knowledge Base.
This is true if the registered country is a member state of the European
Union. Otherwise, the key is not included in the registered_country
object.
Learn more about the European Union flag on our Knowledge Base.
A map from locale codes, such as en, to the localized names for the
feature.
Learn more about localized geolocation names on our Knowledge Base.
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.
Learn about represented countries on our Knowledge Base.
This is true if the registered country is a member state of the European
Union. Otherwise, the key is not included in the represented_country
object.
Learn more about the European Union flag on our Knowledge Base.
The type of represented country. Currently limited to military, but may
include other types in the future.
Learn more about localized geolocation names on our Knowledge Base.
An array of subdivision JSON objects. Subdivisions are arranged from largest to smallest.
A JSON object containing details about a subdivision of the country in which the IP address resides.
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.
A map from locale codes, such as en, to the localized names for the
feature.
Learn more about localized geolocation names on our Knowledge Base.
A JSON object containing general traits associated with the IP address.
The autonomous system number associated with the IP address.
Learn more about autonomous system data on our Knowledge Base.
The organization associated with the registered autonomous system number for the IP address.
Learn more about autonomous system data on our Knowledge Base.
One of the following values: Cable/DSL, Cellular, Corporate, or
Satellite. Additional values may be added in the future.
This field is not present in the GeoLite2 City web service.
Learn more about connection type data on our Knowledge Base.
The second level domain associated with the IP address. This will be something like “example.com” or “example.co.uk”, not “foo.example.com”.
This field is not present in the GeoLite2 City web service.
This is true if the IP address belongs to any sort of anonymous network.
Otherwise, the key is not included in the traits object.
Learn more about anonymizer and proxy detection on our Knowledge Base.
Consider using one of our anonymizer service outputs, such as is_anonymous
and is_anonymous_vpn. These anonymizing service outputs are available in
the GeoIP2 Anonymous IP database
and the GeoIP2 Insights web services.
This is true if the IP address is registered to an anonymous VPN provider.
Otherwise, the key is not included in the traits object.
If a VPN provider does not register subnets under names associated with
them, we will likely only flag their IP ranges using the
is_hosting_provider flag.
This is true if the IP address belongs to a hosting or VPN provider
(see description of is_anonymous_vpn flag). Otherwise, the key is not
included in the traits object.
Learn more about hosting providers used for anonymizing on our Knowledge Base.
This is true if the IP address belongs to a public proxy. Otherwise, the
key is not included in the traits object.
This is true if the IP address is on a suspected anonymizing network and
belongs to a residential ISP (does not include peer-to-peer proxy IPs).
Otherwise, the key is not included in the traits object.
This is true if the IP address is a Tor exit node. Otherwise, the key is
not included in the traits object.
The name of the ISP associated with the IP address.
This field is not present in the GeoLite2 City web service.
The mobile country code (MCC) associated with the IP address and ISP.
This field is not present in the GeoLite2 City web service.
Learn more about mobile country code data on our Knowledge Base.
The mobile network code (MNC) associated with the IP address and ISP.
This field is not present in the GeoLite2 City web service.
Learn more about mobile network code data on our Knowledge Base.
The network in CIDR notation
associated with the record. In particular, this is the largest network where
all of the fields besides ip_address have the same value.
The name of the organization associated with the IP address.
This field is not present in the GeoLite2 City web service.
An indicator of how static or dynamic an IP address is. The value ranges
from 0 to 99.99 with higher values meaning a greater static association. For
example, many IP addresses with a user_type of cellular have a score
under one. Broadband IPs that don’t change very often typically have a score
above thirty.
This indicator can be useful for deciding whether an IP address represents the same user over time.
The estimated number of users sharing the IP/network during the past 24 hours. For IPv4, the count is for the individual IP. For IPv6, the count is for the /64 network.
The user type associated with the IP address. This will be one of the following values:
businesscafecellularcollegeconsumer_privacy_networkcontent_delivery_networkgovernmenthostinglibrarymilitaryresidentialrouterschoolsearch_engine_spidertraveler
A JSON object containing information related to your MaxMind account.
The approximate number of remaining queries available for the end point which is being called.
This field is not present in the GeoLite2 City web service.
Miscellaneous Notes
Languages
Many of the objects listed above 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 is possible that we might
not have any name data at all for a given object.
Returned Values as Database, Map, Dict, or Hash Keys
We strongly discourage you 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 |
This page was last updated on April 12, 2024.