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.

Usage Notice

We recommend integrating with our other GeoIP2 Precision Web Service client APIs or GeoIP2 databases instead of the GeoIP2 JavaScript Client API, since a server-side integration is more secure and more robust than a client-side integration. If you choose to integrate using the GeoIP2 JavaScript Client API, we recommend monitoring your query usage for unexpected spikes.

Service Plans

For more information about the GeoIP2 Precision services and to purchase lookups for use with the API, please visit our web services order page.


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.


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

<script src="//" type="text/javascript"></script>


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


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

Function Description, onError, options) Calls the GeoIP2 Precision: Country endpoint using the routable IP address associated with the machine on which it is running., 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.


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 add missing arrays and objects. 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:

  "city":     {
      "names": {}
  "country":   ...,
  "continent": ...,

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

  "city":         ...,
  "country":      ...,
  "continent":    ...,
  "subdivisions": [ { "names": {} } ],

Sample Code

<script type="text/javascript" src="//"></script>

<script type="text/javascript">

var onSuccess = function(location){
      "Lookup successful:\n\n"
      + JSON.stringify(location, undefined, 4)

var onError = function(error){
      + JSON.stringify(error, undefined, 4)
};, onError);



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

You have not supplied a valid IPv4 or IPv6 address.


You have not supplied an IP address, which is a required field.


You have supplied an IP address which belongs to a reserved or private range.


The supplied IP address is not in the database.


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.


You do not have permission to use the service. Please contact for more information.


The request to the GeoIP2 web service timed out.


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


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. In order to ensure your data is as safe and secure as possible, we recommend using the encrypted HTTP (HTTPS) protocol.

Here is the list of browsers supported:

Browser Version(s)
Chrome Last two stable releases per Chrome Release Stable Channels
Firefox 60+
Internet Explorer 11
Edge 17+
Safari (desktop and mobile) 10+
Opera Current release
Android native browser 5+
iOS native browser 10+


We require TLS 1.2 or greater for HTTPS requests to our servers to keep your data secure.