GeoIP2 JavaScript Client API

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.

Service Plans

To purchase lookups for use with the API, please visit our web services order page.

Registration

All domains using the service must be registered. New users may purchase web service lookups and receive an account to register domains. Existing account holders are able to register domains directly.

JavaScript

In order to use this service, the following JavaScript must be included in your page:

Tutorial

For a step by step walk-through of how to use this API for several different tasks, please see our GeoIP2 JavaScript tutorial.

API

After the geoip2.js script is imported, you will have the geoip2 module in your namespace. This module provides three functions:

Function Description
geoip2.country(onSuccess, onError, options) Calls the GeoIP2 Precision: Country endpoint using the routable IP address associated with the machine on which it is running.
geoip2.city(onSuccess, onError, options) Calls the GeoIP2 Precision: City endpoint using the routable IP address associated with the machine on which it is running.
geoip2.insights(onSuccess, onError, options) Calls the GeoIP2 Precision: Insights endpoint using the routable IP address associated with the machine on which it is running.

Parameters

All of the functions take the same three arguments:

  • If successful, this function calls the onSuccess. The first parameter passed to the callback contains an object matching the output of one of MaxMind’s Precision web service API responses.

    In addition to the attributes listed in the web services API docs, the object also has a most_specific_subdivision property that provides access to the most specific subdivision object available. On browsers other than Internet Explorer 8, this is implemented as a non-enumerable property using defineProperty.

  • If there is an error, the function calls the onError with the error object as a parameter.
  • The options parameter is an object containing flags for the service. This parameter is reserved for future use. There are no options at this time.

Successful Response

A successful response consists of a single JavaScript object. That object contains a set of key/value pairs, where the keys are things like country and traits, and the values are objects or arrays of objects.

While our REST API is documented as omitting keys, for the JavaScript API, we fill in missing data structures. This makes it much simpler to work with the response, as you will not need to check whether the data structure exists before using it.

Wherever a property’s value could be an object or array, we will add an empty object or array as needed. For example, if you call the city() method and the response from the MaxMind server has no city key at all, it will end up being filled in as:

If the response contains no subdivisions key you will get this:

Sample Code

Errors

All errors are passed in a JavaScript object as the first parameter to the onError function. This object contains two keys, code and error. code is a machine-readable error code that will not change. error is a human-readable description of the error.

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.

DOMAIN_REGISTRATION_REQUIRED 401 Unauthorized

The domain of your site is not registered.

QUERY_FORBIDDEN 401 Unauthorized

You tried to access a service or feature that is not covered by your service plan.

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.

HTTP_TIMEOUT (none)

The request to the GeoIP2 web service timed out.

HTTP_ERROR (none)

There was an error making the request to the GeoIP2 web service.

Versioning

This document covers version 2.1 of the GeoIP2 JavaScript API. Whenever MaxMind releases a new version of the JavaScript API, we will use a new path, so the old JavaScript files will always be accessible. For example, if we released version 42.6 of the JavaScript API, its path would be /js/apis/geoip2/v42.6/geoip2.js.

However, support will only be provided for the newest version of the JavaScript API at any given time.

Please note that the JavaScript API and the web service REST API are versioned separately. We will bump the JavaScript API version when we add new features or need to break backwards compatibility with previous versions of the JavaScript API.

Version 2.1 of the JavaScript API uses version 2.1 of the GeoIP2 Precision web services REST API.

Release Notes

Changes to the JavaScript API are documented in our release notes.

Browser Support

MaxMind is committed to support all browser versions that are currently supported by their respective creators. When the creator offers multiple support levels, we only support the browser through its initial support phase. For example, Microsoft has two supports phases, Mainstream and Extended. We are committed to supporting browsers through the end of the Mainstream support phase. We reserve the right to end support at any time for any browser no longer supported by its creator.

Here is the list of browsers with which we test this API:

Browser Platform(s) Version(s)
Chrome Windows XP, 7, 8 Last two stable releases
Linux
OS X 10.6
Firefox Windows XP, 7, 8, 8.1 4+
Linux
OS X 10.6
Internet Explorer Windows XP 8
Windows 7 8, 9, 10, 11
Windows 8 10
Windows 8.1 11
Safari Windows 7 5
OS X 10.6 5
OS X 10.8 6
OS X 10.9 7
Opera Windows XP, 7 11-12
Linux 12
(native browser) iOS 4.3, 5, 5.1, 6, 6.1, 7, 7.1
(native browser) Android 4.0, 4.1, 4.2, 4.3