IP Geolocation

IP Geolocation provides real-time and accurate IP to geolocation API and timezone API. Using geolocation API, you can geolocate your online visitors and provide them customized experience accordingly. The time zone API can be used to get accurate, real-time timezone related information.

This documentation provides API features and available options in detail. For information related to our IP Geolocation Database, please contact our support.

Authorization

We provide two types of authorizations which are:

  • API Key
  • Request Origin

In order to use this API, sign up for the desired plan.

All of our paid plans come with 7 days free trial. We also have a free plan which gives you 50K requests per month. We provide the same API response in our free as well as paid plans with https. Bulk API and Request Origin support are not available for free plans, however.

Here is an overview of both authorization methods.

API Key

You can make authorized requests to our API by passing API key as a query parameter. To get your API key, login to our API console and get your API key from there. We strongly discourage the use of API key in client-side JavaScript as it will expose your API key to the public.

In order to use API key in the client-side JavaScript, use the Request Origin approach.

Request Origin

This feature is available for paid plans only. The purpose of this feature is to call our API from the client-side JavaScript without using your API key.

To use this feature, go to application console and click on Add New button in the dashboard section. A popup will open up. Enter the domain name of the website from where you'll be making requests. If your website is https://www.example.com, you should enter example.com in that pop up as your request origin.

Once saved successfully, you can make requests from the main domain as well as all of the subdomains of the main website.

Limit on No. of Request Origins

The number of request origins is limited based on the user's plan.

Subscription PlanNo. of Request Origins
Bronze1
Bronze+1
Silver2
Silver+2
Gold3
Platinum3
Diamond3

To add more request origin than your limit, you can leave a message at contact us. Extra request origins are charged $5 per origin per month.

IP Geolocation API

We provide three endpoints in our GeoIP API.

Get IP

Get IP endpoint returns the IP address of the client from where it's called. So if you call it from your server, it returns IP of the server. If it's called from your website JavaScript, it will return the IP address of the person viewing your website. This endpoint does not require any API key and you can use this endpoint without creating an account. Here is a curl example:

$ curl 'https://api.ipgeolocation.io/getip'

Single IP Geolocation Lookup API

Single IP Location API can be used to lookup any IPv4 or IPv6 address with JSON response. The URL for this endpoint is https://api.ipgeolocation.io/ipgeo and its full JSON response is below:

{
    "ip": "8.8.8.8",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "country_capital": "Washington",
    "state_prov": "California",
    "district": "Santa Clara County",
    "city": "Mountain View",
    "zipcode": "94043",
    "latitude": "37.4229",
    "longitude": "-122.085",
    "is_eu": false,
    "calling_code": "+1",
    "country_tld": ".us",
    "languages": "en-US,es-US,haw,fr",
    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
    "isp": "Level 3 Communications",
    "connection_type": "",
    "organization": "Google Inc.",
    "geoname_id": "5375480",
    "currency": {
        "name": "US Dollar",
        "code": "USD"
    },
    "time_zone": {
        "name": "America/Los_Angeles",
        "offset": -8,
        "current_time": "2018-10-15 08:07:01.552-0700",
        "is_dst": true,
        "dst_savings": 1
    }
}

Single IP API can be used in two ways.

Passing an IPv4 or IPv6 Address

In order to find geolocation information about an IP address, pass it as a query parameter like below. Note that apiKey is also passed as a query parameter for authorization. This endpoint is meant to be called from the server side.

# Get details for IPv4 IP Address = 1.1.1.1
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1'

# Get details for IPv6 IP Address = 2001:4860:4860::1
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=2001:4860:4860::1'

Without Passing an IP Address

When the IP address is not present, it returns the geolocation information of the device/client which is calling it. This endpoint is meant to be called from client side.

$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY'
* IP address is always included in the API response

Note: When this endpoint is being called from client-side using Request Origin, apiKey parameter has to be removed.

Bulk IP Geolocation Lookup API

This feature is only available for paid plans. This endpoint allows you to perform the lookup of multiple IPv4 and IPv6 addresses (max. 50) at the same time. The requests count per lookup is equal to total IP addresses passed.

To perform bulk IP Geolocation Lookup send a POST request and pass the "ips" array as JSON data along with it. Here is an example.

$ curl -X POST 'https://api.ipgeolocation.io/ipgeo-bulk?apiKey=API_KEY'
  -H 'Content-Type: application/json'
  -d '{ "ips": ["1.1.1.1", "1.2.3.4"] }'

Filter Responses

We've built our API to give you fine granularity. Specify what you want in query parameter and get only those fields. This will save processing time, bandwidth and improve the API response time.

Get the Required Fields/Objects

Instead of getting the full response, you can filter the API response by specifying the name of fields/objects as needed. Name of the fields/objects must be passed as a query parameter fields in the request. Here are a few examples to get only the required fields:

Get City Information
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=city'
{
    "ip": "1.1.1.1",
    "city": "South Brisbane"
}
Get Country Name and Country Code in ISO2 Format
curl $ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=country_code2,country_name'
{
    "ip": "1.1.1.1",
    "country_code2": "AU",
    "country_name": "Australia"
}

Get The Time Zone Information from the IP Address
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=time_zone'
{
    "ip": "1.1.1.1",
    "time_zone": {
        "name": "Australia/Brisbane",
        "offset": 10,
        "current_time": "2018-07-27 17:43:07.311+1000",
        "is_dst": false,
        "dst_savings": 0
    }
}
Get The Local Currency Information of multiple IP Addresses

You can use our filters with Bulk IP Lookup as well. Here is an example:

$ curl -X POST 'https://api.ipgeolocation.io/ipgeo-bulk?apiKey=API_KEY&fields=currency'
  -H 'Content-Type: application/json'
  -d '{ "ips": ["1.1.1.1", "1.2.3.4"] }'
[
    {
        "ip": "1.1.1.1",
        "currency": {
            "name": "Australian Dollar",
            "code": "AUD"
        }
    },
    {
        "ip": "1.2.3.4",
        "currency": {
            "name": "Australian Dollar",
            "code": "AUD"
        }
    }
]
Get Geo Location Only

We know, most of the times, users are interested in geolocation information only. So, we have added a shortcut for you. You can specify just fields=geo in your query parameter.

$ curl 'api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=geo'
{
    "ip": "1.1.1.1",
    "country_code2": "AU",
    "country_code3": "AUS",
    "country_name": "Australia",
    "state_prov": "Queensland",
    "district": "Brisbane",
    "city": "South Brisbane",
    "zipcode": "4101",
    "latitude": "-27.4748",
    "longitude": "153.017"
}

Exclude Filters

You can also filter the API response by specifying the name of fields/objects that you want to remove from the API response. Name of the fields/objects must be passed as a query parameter excludes in the request. Here are a few examples to exclude the unnecessary fields:

Exclude continent_code,currency,time_zone objects
curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&excludes=continent_code,currency,time_zone'
{
    "ip": "1.1.1.1",
    "continent_name": "Oceania",
    "country_code2": "AU",
    "country_code3": "AUS",
    "country_name": "Australia",
    "country_capital": "Canberra",
    "state_prov": "Queensland",
    "district": "Brisbane",
    "city": "South Brisbane",
    "zipcode": "4101",
    "latitude": "-27.4748",
    "longitude": "153.017",
    "is_eu": false,
    "calling_code": "+61",
    "country_tld": ".au",
    "languages": "en-AU",
    "country_flag": "https://ipgeolocation.io/static/flags/au_64.png",
    "isp": "Cloudflare Inc.",
    "connection_type": "",
    "organization": "",
    "geoname_id": "2207259"
}
Get the geo field and exclude continent information
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=geo&excludes=continent_code,continent_name'
{
    "ip": "1.1.1.1",
    "country_code2": "AU",
    "country_code3": "AUS",
    "country_name": "Australia",
    "state_prov": "Queensland",
    "district": "Brisbane",
    "city": "South Brisbane",
    "zipcode": "4101",
    "latitude": "-27.4748",
    "longitude": "153.017"
}
Get country_code2 and exclude the 'ip' from Bulk IP Lookup
$ curl -X POST 'https://api.ipgeolocation.io/ipgeo-bulk?apiKey=API_KEY&fields=country_code2&excludes=ip'
  -H 'Content-Type: application/json'
  -d '{ "ips": ["1.1.1.1", "1.2.3.4"] }'
[
    {
        "country_code2": "AU"
    },
    {
        "country_code2": "AU"
    }
]

Timezone API

Timezone API provides time zone related information for an IP address, Timze Zone and, Latitude and Longitude pair.

Here is the full response of this API

{  
    "geo": {  
        "country_code2": "AU",  
        "country_code3": "AUS",  
        "country_name": "Australia",  
        "state_prov": "Queensland",  
        "district": "Brisbane",  
        "city": "South Brisbane",  
        "zipcode": "4101",  
        "latitude": "-27.4748",  
        "longitude": "153.017"  
    },  
    "timezone": "Australia/Brisbane",  
    "timezone_offset": 10,  
    "date": "2018-07-27",  
    "date_time": "2018-07-27 07:57:25",  
    "date_time_txt": "Friday, July 27, 2018 07:57:25",  
    "date_time_wti": "Fri, 27 Jul 2018 07:57:25 +0000",  
    "date_time_ymd": "2018-07-27T07:57:25+0000",  
    "time_24": "07:57:25",  
    "time_12": "07:57:25 AM",  
    "week": "30",  
    "month": "07",  
    "year": "2018",  
    "year_abbr": "18",  
    "is_dst": false,  
    "dst_savings": 0  
}

Timezone API has four different variations. Here is the detail for each. The response in each variation remains the same, however, the different input source is passed in each variation.

Passing TimeZone

$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&tz=America/Los_Angeles'

Passing Latitude and Longitude

Pass latitude and longitude of a location as a query parameter to get the timezone information. Here is an example call:

$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&lat=-27.4748&long=153.017'

Passing an IPv4 or IPv6 Address

You can pass an IPv4 or IPv6 address as a query parameter to get the regional timezone information.

$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&ip=1.1.1.1'

Using Client or Machine IP Address

You can call the timezone API without passing any information as well. It will use the calling machine's IP address to return the regional timezone information. Here is an example call:

$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY'

This variation is widely used on embedded hardware in IoT to get current time after reboot.

Note 1: When you get the timezone information through an IP address, API will also return the 'geo' field along with the timezone information.

Note 2: In above example, we used API Key everywhere. Time Zone API can be called from client side JavaScript with Request Origin as well on paid plans.

Security / SSL

We take security seriously and all of our API endpoints are served over a secure HTTPS connection for all users, even if you are on the free plan.

Rate Limits

We don't have any daily, hourly or monthly rate limit on any of our paid plans. If you increase from your monthly quota, we'll keep serving your requests and add a surcharge amount on top of your monthly price. Surcharge rate varies from plan to plan.

We have a hard limit of 50,000 requests per month on our Free plan and 100,000 requests for 7 days on trial accounts.

API SDKs

To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.

Our SDKs are also available on Github. Feel free to help us improve them. SDKs. Following are the available SDKs: