GeoIP2 Web Services

If you are a GeoIP Legacy customer, please see our “What’s New in GeoIP2″ document for a general overview of the changes from GeoIP Legacy 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
Perl CPAN MetaCPAN GitHub
PHP Packagist GitHub Pages GitHub
Python PyPI Read the Docs GitHub

Third-Party APIs

Warning! MaxMind does not offer support for these APIs and has not reviewed the code. Use at your own risk.
Language or Framework API Name Package Repository Documentation Version Control
Node.js nodejs-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.

Service URI Content-Type
Country https://geoip.maxmind.com/geoip/v2.0/country/{ip_address} application/vnd.maxmind.com-country+json; charset=UTF-8; version=2.0
City (Precision) https://geoip.maxmind.com/geoip/v2.0/city/{ip_address} application/vnd.maxmind.com-city+json; charset=UTF-8; version=2.0
City/ISP/Org (Precision) https://geoip.maxmind.com/geoip/v2.0/city_isp_org/{ip_address} application/vnd.maxmind.com-city-isp-org+json; charset=UTF-8; version=2.0
Omni (Precision) https://geoip.maxmind.com/geoip/v2.0/omni/{ip_address} application/vnd.maxmind.com-omni+json; charset=UTF-8; version=2.0

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

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 demo 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 404 Not Found 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.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.

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:

{
    "city":                { ... },
    "continent":           { ... },
    "country":             { ... },
    "location":            { ... },
    "postal":              { ... },
    "registered_country":  { ... },
    "represented_country": { ... },
    "subdivisions":        [{ ... }, ... ],
    "traits":              { ... },
    "maxmind":             { ... }
}

The exact set of top-level keys varies based on the particular GeoIP service you are using. If a key maps to an undefined 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.

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? City/ISP/Org? Omni?
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? City/ISP/Org? Omni?
code string (2)

A two-character code for the continent associated with the IP address. The possible codes are:

  • AF - Africa
  • 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? City/ISP/Org? Omni?
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? City/ISP/Org? Omni?
accuracy_radius integer The radius in kilometers around the specified location where the IP address is likely to be.
latitude decimal The latitude of the location associated with the IP address.
longitude decimal The longitude of the location 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 the Google AdWords API.
time_zone string The time zone associated with location, as specified by the IANA Time Zone Database, e.g., “America/New_York”.

postal

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

Included in …
Key Value Type Description Country? City? City/ISP/Org? Omni?
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? City/ISP/Org? Omni?
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 or embassy.

Included in …
Key Value Type Description Country? City? City/ISP/Org? Omni?
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 embassy and 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? City/ISP/Org? Omni?
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? City/ISP/Org? Omni?
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 true if the IP is an anonymous proxy. Otherwise, the key is not included in the traits object.
is_satellite_provider boolean true if the IP address is from a satellite provider that provides service to multiple countries.
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? City/ISP/Org? Omni?
queries_remaining integer The approximate number of remaining queries available for the end point which is being called.

Output Examples

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

{
    "city":  {
        "confidence":  25,
        "geoname_id": 54321,
        "names":  {
            "de":    "Los Angeles",
            "en":    "Los Angeles",
            "es":    "Los Ángeles",
            "fr":    "Los Angeles",
            "ja":    "ロサンゼルス市",
            "pt-BR":  "Los Angeles",
            "ru":    "Лос-Анджелес",
            "zh-CN": "洛杉矶"
        }
    },
    "continent":  {
        "code":       "NA",
        "geoname_id": 123456,
        "names":  {
            "de":    "Nordamerika",
            "en":    "North America",
            "es":    "América del Norte",
            "fr":    "Amérique du Nord",
            "ja":    "北アメリカ",
            "pt-BR": "América do Norte",
            "ru":    "Северная Америка",
            "zh-CN": "北美洲"

        }
    },
    "country":  {
        "confidence":  75,
        "geoname_id": "6252001",
        "iso_code":    "US",
        "names":  {
            "de":     "USA",
            "en":     "United States",
            "es":     "Estados Unidos",
            "fr":     "États-Unis",
            "ja":     "アメリカ合衆国",
            "pt-BR":  "Estados Unidos",
            "ru":     "США",
            "zh-CN":  "美国"
        }
    },
    "location":  {
        "accuracy_radius":   20,
        "latitude":          37.6293,
        "longitude":         -122.1163,
        "metro_code":        807,
        "time_zone":         "America/Los_Angeles"
    },
    "postal": {
        "code":       "90001",
        "confidence": 10
    },
    "registered_country":  {
        "geoname_id": "6252001",
        "iso_code":    "US",
        "names":  {
            "de":     "USA",
            "en":     "United States",
            "es":     "Estados Unidos",
            "fr":     "États-Unis",
            "ja":     "アメリカ合衆国",
            "pt-BR":  "Estados Unidos",
            "ru":     "США",
            "zh-CN":  "美国"
        }
    },
    "represented_country":  {
        "geoname_id": "6252001",
        "iso_code":    "US",
        "names":  {
            "de":     "USA",
            "en":     "United States",
            "es":     "Estados Unidos",
            "fr":     "États-Unis",
            "ja":     "アメリカ合衆国",
            "pt-BR":  "Estados Unidos",
            "ru":     "США",
            "zh-CN":  "美国"
        },
        "type": "military"
    },
    "subdivisions":  [
        {
            "confidence":  50,
            "geoname_id": 5332921,
            "iso_code":    "CA",
            "names":  {
                "de":    "Kalifornien",
                "en":    "California",
                "es":    "California",
                "fr":    "Californie",
                "ja":    "カリフォルニア",
                "ru":    "Калифорния",
                "zh-CN": "加州"
            }
        }
    ],
    "traits": {
        "autonomous_system_number":      "1239",
        "autonomous_system_organization": "Linkem IR WiMax Network",
        "domain":                        "example.com",
        "is_anonymous_proxy":            true,
        "is_satellite_provider":         true,
        "isp":                           "Linkem spa",
        "ip_address":                    "1.2.3.4",
        "organization":                  "Linkem IR WiMax Network",
        "user_type":                     "traveler",
    },
    "maxmind": {
        "queries_remaining":            "54321"
    }
}

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.

(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 web services are documented in our release notes.

Versioning

The GeoIP2 web services use two part versions. Our first release is version 2.0. The major version number will remain at 2 for the forseeable 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.0/inter-galactic. This should not break any existing client code.