GeoIP JavaScript

Table of Contents

MaxMind offers an API which returns JavaScript code for the client's IP address. This comes in two flavors, city and country. This service can be purchased separately from our other GeoIP web services.

This service was previously available in various free offerings. These were discontinued as of May 1. Please see the GeoIP2 JavaScript service for our current free offerings.

You can include the JavaScript provided by MaxMind in your web pages. This script creates several window-global functions that return information about the client's IP address.

Registration

All domains using the service must be registered. New users may sign up for an account. Existing users are able to register domains directly.

Per-Service URIs

The URIs for each service are as follows:

Service URI <script> tag
Country http://j.maxmind.com/js/country.js <script src="//j.maxmind.com/js/country.js" type="text/javascript"></script>
City http://j.maxmind.com/js/geoip.js <script src="//j.maxmind.com/js/geoip.js" type="text/javascript" ></script>

The use of the charset attribute in the script tag should cause modern browsers to decode the content of the JavaScript script so that it matches the encoding of the web page.

Unlike some of our other web services, the JavaScript service only has one hostname.

Output

Both of these services create a set of global functions, each of which returns a single item of information about the client's IP. Note that some functions may return an empty string. This happens if we do not have that piece of information for a given IP. If the IP address is a private IP address or not in our database at all, all of the functions will return an empty string.

Included in ...
Function Name Type (length) Description Country? City? Your IP
geoip_city() string The city or town name associated with the IP address. See our list of cities to see all the possible return values. This list is updated on a regular basis.
geoip_region() string (2)

A two character ISO-3166-2 or FIPS 10-4 code for the state/region associated with the IP address.

For the US and Canada, we return an ISO-3166-2 code. In addition to the standard ISO codes, we may also return one of the following:

  • AA - Armed Forces America
  • AE - Armed Forces Europe
  • AP - Armed Forces Pacific

We return a FIPS code for all other countries.

We provide a CSV file which maps our region codes to region names. The columns are ISO country code, region code (FIPS or ISO), and the region name.

geoip_region_name() string The region name associated with the IP address.
geoip_postal_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.
geoip_country_code() string (2)

A two-character ISO 3166-1 country code for the country associated with the IP address. In addition to the standard codes, we may also return one of the following:

The US country code is returned for IP addresses associated with overseas US military bases.

geoip_country_name() string The country name associated with the IP address.
geoip_latitude() decimal The latitude associated with the IP address. The latitude and longitude are near the center of the most granular location value returned: postal code, city, region, or country.
geoip_longitude() decimal The longitude associated with the IP address.

Error Codes

This service returns an HTTP status code if there is an error.

HTTP Status Code Reason
400 Bad Request This code is returned if the requesting IP address is not found in our database.
401 Unauthorized The referring domain has not been registered.

Example

<!DOCTYPE HTML>

<html>
<head>
  <script type="text/javascript" src="//j.maxmind.com/js/geoip.js">
  </script>

  <title>JS Example</title>
</head>

<body>

  <dl>

    <dt>City</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_city() );
      </script>
    </dd>

    <dt>Region</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_region() );
      </script>
    </dd>

    <dt>Region Name</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_region_name() );
      </script>
    </dd>

    <dt>Postal Code</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_postal_code() );
      </script>
    </dd>

    <dt>Country Code</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_country_code() );
      </script>
    </dd>

    <dt>Country Name</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_country_name() );
      </script>
    </dd>

    <dt>Latitude</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_latitude() );
      </script>
    </dd>

    <dt>Longitude</dt>
    <dd>
      <script type="text/javascript">
        document.write( geoip_longitude() );
      </script>
    </dd>

  </dl>

</body>
</html>