Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more

Documentation

Integrating the IP geolocation API in your applications is very easy and language agnostic. The API endpoint returns the results for your queries in JSON format, therefore you can consume these results with any programming language or tool that understands JSON.

We use geolocation data from multiple sources and support both IPv4 and IPv6 addresses.

Examples

To get all the geolocation details for your current IP address (or the IP address of the computer making the request), try this example (with curl) from the command line:

curl https://www.hatuko.com/myip

This is equivalent of:

curl https://www.hatuko.com/api/v1/geolocation/lookup/self

The request will return something like the JSON below, which includes all the available fields:

{
  result: "success",
  remaining_queries: 995,
  data: {
    ip_address: "179.126.29.132",
    hostname: "179-126-029-132.xd-dynamic.algarnetsuper.com.br",
    asn: 53006,
    organization: "ALGAR TELECOM S/A",
    continent_code: "SA",
    continent_name: "South America",
    country_code: "BR",
    country_name: "Brazil",
    flag: "https://cdnjs.cloudflare.com/ajax/libs/flag-icon-css/2.8.0/flags/4x3/br.svg",
    time_zone: "America/Sao_Paulo",
    region_code: "SP",
    region_name: "Sao Paulo",
    city: "Miguelopolis",
    postal_code: 45921,
    latitude: -20.1811,
    longitude: -48.0297,
    accuracy_radius: 100
  }
}

NOTE: Requests to the /lookup/self endpoint do not count against your daily quota.

If you want to use only one field from the command line, you can for example use the jq command together with curl:

curl https://www.hatuko.com/myip | jq '.data.country_code'

In the example above, the command will return only the country code.

You can also limit which fields are returned in the JSON response by specifying the ones that you need by adding the fields parameter, which expects a list of field names separated by commas:

curl https://www.hatuko.com/api/v1/geolocation/lookup/self?fields=country_code,country_name,flag

The response will be something like this:

{
  result: "success",
  remaining_queries: 995,
  data: {
    country_code: "BR",
    country_name: "Brazil",
    flag: "https://cdnjs.cloudflare.com/ajax/libs/flag-icon-css/2.8.0/flags/4x3/br.svg",
  }
}

To perform a lookup of a specific IP address, just replace self with the IP address:

curl https://www.hatuko.com/api/v1/geolocation/lookup/179.126.29.132

NOTE: Without an API key you are allowed to make up to 10,000 IP lookups per day.

With an API key you can make as many requests per day as allowed by your plan. You can pass the API key to any request by setting the Authorization header:

curl https://www.hatuko.com/api/v1/geolocation/lookup/179.126.29.132 -H 'Authorization: Token token="87d917ae55bb232877c2ae4f84f9ea46"'

NOTE: Requests which specify an invalid API key will result in a 401 status code (unauthorized), while requests that exceed the daily quota will result in a 429 code. Queries for invalid IP addresses will instead return a 422 code. These failed requests will return the reason for failure in the body, for example:

{
  "result":"error",
  "reason":"Daily quota reached",
  "remaining_queries":0
}

Example with Ruby

Here's an example of lookup with Ruby, using the rest-client gem:

>> require "rest-client"
=> true
>> require "json"
=> true
>> JSON.parse RestClient.get("https://www.hatuko.com/api/v1/geolocation/lookup/179.126.29.132",
 { 'Authorization': 'Token token="87d917ae55bb232877c2ae4f84f9ea46"' })
=> {"result"=>"success", "data"=>{"ip_address"=>"179.126.29.132",...

If you have any questions please don't hesitate to contact us (support @ hatuko.com).