GeoIP and GeoLite API Responses

Headers

The Content-Type for a successful response varies based on the service as outlined below:

ServiceContent-Type
GeoIP2 Countryapplication/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1
GeoIP2 Cityapplication/vnd.maxmind.com-city+json; charset=UTF-8; version=2.1
GeoIP2 Insightsapplication/vnd.maxmind.com-insights+json; charset=UTF-8; version=2.1
GeoLite2 Countryapplication/vnd.maxmind.com-country+json; charset=UTF-8; version=2.1
GeoLite2 Cityapplication/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 Precision Country 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 Precision City 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 Precision City 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

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.

AUTHORIZATION_INVALID

401 Unauthorized

You have supplied an invalid MaxMind account 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.

ACCOUNT_ID_REQUIRED

401 Unauthorized

You have not supplied a MaxMind account ID in the Authorization header.

INSUFFICIENT_FUNDS

402 Payment Required

The license key you have provided does not have sufficient funds to use this service. Please purchase more service credits.

PERMISSION_REQUIRED

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.

IP_ADDRESS_NOT_FOUND

404 Not Found

The supplied IP address is not in the database.

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

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.

Responseobject

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

Example
cityobject

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

Example
CountryCityInsights
continentobject

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

Example
CountryCityInsights
countryobject

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

Example
CountryCityInsights
locationobject

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

Example
CountryCityInsights
postalobject

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

Example
CountryCityInsights
registered_countryobject

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

Example
CountryCityInsights
represented_countryobject

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.

Example
CountryCityInsights
subdivisionsarray

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.

Example
CountryCityInsights
traitsobject

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

Example
CountryCityInsights
maxmindobject

A JSON object containing information related to your MaxMind account.

Example
CountryCityInsights

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

Example
confidenceinteger

A value from 0-100 representing our confidence that the city is correct.

Example
Min: 0Max: 100
CountryCityInsights
geoname_idinteger

A unique identifier for the city as specified by GeoNames.

Example
CountryCityInsights
namesobject

A map from locale codes, such as en, to the localized names for the feature.

Example
CountryCityInsights

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

Example
codestring

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
Example
CountryCityInsights
geoname_idinteger

A unique identifier for the continent as specified by GeoNames.

Example
CountryCityInsights
namesobject

A map from locale codes, such as en, to the localized names for the feature.

Example
CountryCityInsights

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

Example
confidenceinteger

A value from 0-100 representing our confidence that the country is correct.

Example
Min: 0Max: 100
CountryCityInsights
is_in_european_unionboolean

This is true if the country is a member state of the European Union. Otherwise, the key is not included in the country object.

Example
CountryCityInsights
iso_codestring

A two-character ISO 3166-1 country code for the country associated with the IP address.

Example
Length: 2
CountryCityInsights
namesobject

A map from locale codes, such as en, to the localized names for the feature.

Example
CountryCityInsights

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

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

Example
CountryCityInsights
average_incomeinteger

The average annual income associated with the IP address in US dollars. This is only available for IP addresses in the US.

Example
CountryCityInsights
latitudenumber

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.

Example
Format: Decimal
CountryCityInsights
longitudenumber

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.

Example
Format: Decimal
CountryCityInsights
metro_codeinteger

The metro code associated with the IP address. These are only available for IP addresses in the US.

Example
CountryCityInsights
population_densityinteger

The estimated number of people per square kilometer. This is only available for IP addresses in the US.

CountryCityInsights
time_zonestring

The time zone associated with location, as specified by the IANA Time Zone Database, e.g., "America/New_York".

Example
CountryCityInsights

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

Example
codestring

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
Example
CountryCityInsights
confidenceinteger

A value from 0-100 representing our confidence that the postal code is correct.

Example
Min: 0Max: 100
CountryCityInsights

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

Example
geoname_idinteger

A unique identifier for the country as specified by GeoNames.

Example
CountryCityInsights
is_in_european_unionboolean

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.

Example
CountryCityInsights
iso_codestring

A two-character ISO 3166-1 country code for the registered country.

Example
Length: 2
CountryCityInsights
namesobject

A map from locale codes, such as en, to the localized names for the feature.

Example
CountryCityInsights

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.

Example
geoname_idinteger

A unique identifier for the country as specified by GeoNames.

Example
CountryCityInsights
is_in_european_unionboolean

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.

Example
CountryCityInsights
iso_codestring

A two-character ISO 3166-1 country code for the represented_country country.

Example
Length: 2
CountryCityInsights
namesobject

A map from locale codes, such as en, to the localized names for the feature.

Example
CountryCityInsights
typestring

The type of represented country. Currently limited to military, but may include other types in the future.

Example
CountryCityInsights
Example

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.

Example
confidenceinteger

A value from 0-100 representing our confidence that the region is correct.

Example
Min: 0Max: 100
CountryCityInsights
geoname_idinteger

A unique identifier for the region as specified by GeoNames.

Example
CountryCityInsights
iso_codestring

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.

Example
CountryCityInsights
namesobject

A map from locale codes, such as en, to the localized names for the feature.

Example
CountryCityInsights

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

Example
autonomous_system_numberinteger

The autonomous system number associated with the IP address.

Example
CountryCityInsights
autonomous_system_organizationstring

The organization associated with the registered autonomous system number for the IP address.

Example
CountryCityInsights
domainstring

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.

Example
CountryCityInsights
ip_addressstring

The requested IP address.

Example
CountryCityInsights
is_anonymousboolean

This is true if the IP address belongs to any sort of anonymous network. Otherwise, the key is not included in the traits object.

Example
CountryCityInsights
is_anonymous_proxydeprecated

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 Precision Insights services.

is_anonymous_proxydeprecated

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 Precision Insights services.

is_anonymous_vpnboolean

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.

Example
CountryCityInsights
is_hosting_providerboolean

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.

Example
CountryCityInsights
is_public_proxyboolean

This is true if the IP address belongs to a public proxy. Otherwise, the key is not included in the traits object.

Example
CountryCityInsights
is_residential_proxyboolean

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.

Example
CountryCityInsights
is_tor_exit_nodeboolean

This is true if the IP address is a Tor exit node. Otherwise, the key is not included in the traits object.

Example
CountryCityInsights
ispstring

The name of the ISP associated with the IP address.

This field is not present in the GeoLite2 City web service.

Example
CountryCityInsights
networkstring

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.

Example
CountryCityInsights
organizationstring

The name of the organization associated with the IP address.

This field is not present in the GeoLite2 City web service.

Example
CountryCityInsights
static_ip_scorenumber

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.

Example
Format: DecimalMin: 0Max: 99.99
CountryCityInsights
user_countinteger

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.

Example
CountryCityInsights
user_typestring

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
Example
CountryCityInsights

A JSON object containing information related to your MaxMind account.

Example
queries_remaininginteger

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.

Example
CountryCityInsights

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 objectRecommended key
citygeoname_id
continentcode or geoname_id
country, registered_country, and represented_countryiso_code or geoname_id
postalcode
subdivisionsiso_code or geoname_id

This page was last updated on July 29, 2021.