GeoIP and GeoLite API Requests

Authorization and Security

The HTTP Authorization header is required for authorization. The username is your MaxMind account ID. The password is your MaxMind license key.

You must be approved for a GeoIP2 Precision trial, purchase service credit for use with our web services, or have a GeoLite2 account, in order to receive an account ID and license key.

We use basic HTTP authentication. The APIs which require authentication are only available via HTTPS. The credentials are never transmitted unencrypted. If you attempt to access this service via HTTP, you will receive a 403 Forbidden HTTP response.

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

Service Endpoints

The endpoint for each service is as specified below. Each endpoint expects an IP adddress to be defined as a path parameter ({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.

GeoIP2 Endpoints

ServiceHTTP MethodEndpoint
CountryGEThttps://geoip.maxmind.com/geoip/v2.1/country/{ip_address}
CityGEThttps://geoip.maxmind.com/geoip/v2.1/city/{ip_address}
InsightsGEThttps://geoip.maxmind.com/geoip/v2.1/insights/{ip_address}

The geoip.maxmind.com hostname automatically picks the data center geographically closest to you.

GeoLite2 Endpoints

ServiceHTTP MethodEndpoint
CountryGEThttps://geolite.info/geoip/v2.1/country/{ip_address}
CityGEThttps://geolite.info/geoip/v2.1/city/{ip_address}

The geolite.info hostname automatically picks the data center geographically closest to you.

Headers

The Authorization header is always required. See Authorization and Security for more details.

The Accept header for a request is entirely optional. If you do include one, you must accept one of the following, substituting the [SERVICE-TYPE] with either score, insights, or factors as appropriate:

  • application/json

  • application/vnd.maxmind.com-minfraud-[SERVICE TYPE]+json

  • application/vnd.maxmind.com-minfraud-[SERVICE TYPE]+json; charset=UTF-8; version=2.0

    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.

This page was last updated on June 17, 2021.