We highly recommend using a server-side integration, as it is more secure and more robust than a client-side integration.
1. Register your domain(s)
All domains using the service must be registered. New users may request a free trial or purchase web service credit in order to receive an account to register domains. Existing account holders are able to register domains directly.
3. Call an API method and provide callbacks
|Calls the "GeoIP2 Country" endpoint using the routable IP address associated with the machine on which it is running.|
|Calls the "GeoIP2 City Plus" endpoint using the routable IP address associated with the machine on which it is running.|
|Calls the "GeoIP2 Insights" endpoint using the routable IP address associated with the machine on which it is running.|
All of the functions take the same 3 arguments:
If successful, this function calls the
onSuccesscallback. The first parameter passed to the callback contains an object matching the output of one of MaxMind’s GeoIP2 web service API responses.
In addition to the attributes listed in the web services API docs, the object also has a
most_specific_subdivisionproperty 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
If there is an error, the function calls the
onErrorcallback with the error object as a parameter.
optionsparameter is an object containing flags for the service. This parameter is reserved for future use. There are no options at this time.
Example: Display the user's city name in a page
In this example, we are displaying the user's city name in a page. We have 2 files: page.html and demo.js.
contains a set of key/value pairs, where the keys are things like
traits, and the values are objects or arrays of objects.
Wherever a missing 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
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:
onError function. This object contains two keys,
a machine-readable error code that will not change.
error is a human-readable
description of the error.
|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 firstname.lastname@example.org 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.|
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 support 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:
|Chrome||Last two stable releases per Chrome Release Stable Channels|
|Safari (desktop and mobile)||10+|
|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.
This page was last updated on March 29, 2023.