Your API token is used to authenicate you with our API, and can be provided either as a HTTP Basic Auth username, a bearer token, or alternatively as a token URL parameter.

# With Basic Auth
$ curl -u $TOKEN: 

# With Bearer token
$ curl -H 'Authorization: Bearer $TOKEN' 

# With token query parameter
$ curl$TOKEN 

It's also possible to use the API without authentication in a more limited capacity.

IP Address Parameter

The API supports passing in a single IPv4 or IPv6 IP address. Alternatively if you do not pass in any IP address we'll return details for the calling address. This allows you to lookup your own (or a visitor to your site) IP address details without knowing the IP address in advance.

# Get details for
$ curl$TOKEN 

# Get details for 2001:4860:4860::8888
$ curl$TOKEN

# Get details for your own IP address, which'll be included in the response
$ curl$TOKEN


Our API is available over a secure HTTPS connection for all users, even on the free plan. Simply point add https:// to the requests to make the requests secure.

# Get details for your own IP address over HTTPS
$ curl$TOKEN

Rate Limits

Free usage of our API is limited to 1,000 API requests per day. If you exceed 1,000 requests in a 24 hour period we'll return a 429 HTTP status code to you. Paid plans come with monthly limits, and configurable alerts.

Filtering Responses

You can filter the API response down to specific fields or objects by adding the field or object name to the URL. In the case of a field you'll get it returned in plaintext, and an object will get returned as JSON.

# Get json the org field as plaintext
$ curl
AS15169 Google Inc.

# Get just the city as plaintext
Mountain View

You can also specify /geo to get just the geolocation information, which will often be faster than getting the full response.

$ curl
  "ip": "",
  "loc": "37.385999999999996,-122.0838",
  "city": "Mountain View",
  "region": "California",
  "country": "US"


JSONP and CORS are supported, allowing you to use entirely in client-side code. For JSONP You just need to specify the callback parameter, eg. Most javascript libraries will automatically handle this for you though. Here's a jQuery example that logs the client IP and country:

$.get("", function(response) {
}, "jsonp")