IP Geolocation

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

This documentation provides API features and available options in detail.

 

API Key

To use IP Geolocation APIs, you must pass your API key as query parameter to our APIs for authentication. All of our APIs require an API key to respond successfully to your requests except the one i.e., to get client's IP address. We strongly discourage the use of API key in client side Javascript as it will expose API key to public. If you still need to take action on client IP address from client side, you can use our endpoint which returns client IP only (it does not require an API Key) and use that information in your backend to query our APIs from the code which is not exposed to client. It?s fine to use your API Key in mobile apps.

 

To get your API key, sign up for a desired plan. All of our paid plans come with 7 days trial. We also have a free plan which gives you 50K requests per month. Our free plan has all of the features of our paid plan except that it has lower requests limit.

 

After signing up, sign in to get your API key and see other statistics.

 

Get IP

Get IP endpoint returns the IP address of the client from where its called. So if you call it from your backend, it returns IP of the server. If its called from your website Javascript, it will return the IP address of the person viewing your website. The purpose of this endpoint is to get client IP address and use it for geolocation API so that your API key is not exposed to public. This endpoint does not require any API Key.

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


Geolocation API

Geolocation API can be used to lookup any IPv4 or IPv6 address. Geolocation API offers three ways of IP to geolocation lookup:

1. Pass an IPv4 or IPv6 address as query parameter to lookup geolocation.

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

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


2. Do not pass an IP address as query parameter. When the IP address is not present, it returns the geolocation of device / client which is calling it.

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


3. Bulk IP Geolocation Lookup

Ipgeolocation API has ability to lookup multiple IPv4 and IPv6 addresses (max. 50) at the same time. The requests count per lookup is equal to total IP addresses passed.

Important Note: Bulk IP geolocation lookup is only available for paid plans.

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

For bulk IP addresses lookup, send a POST request and pass the ?ips? array as JSON data along with it.

 

Filter Responses

Instead of getting the complete response, you can also filter the response by specifying field/object name as you require. Fields are to be provided as query parameter along with the request. You can specify as many fields as you need.

# Get city information only
$ curl 'https://api.ipgeolocation.info/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 with ISO2 format
$ curl 'https://api.ipgeolocation.info/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 time zone information of the IP Address
$ curl 'https://api.ipgeolocation.info/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 local currency information of multiple IP Addresses
$ curl -X POST 'https://api.ipgeolocation.info/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": "Dollar",
            "code": "AUD"
        }
    },
    {
        "ip": "1.2.3.4",
        "currency": {
            "name": "Dollar",
            "code": "AUD"
        }
    }
]


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

# Get information about IP Location only
$ curl 'api.ipgeolocation.info/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"
}


Geolocation API Full Response

{
    "ip": "1.1.1.1",
    "continent_code": "OC",
    "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",
    "currency": {
        "name": "Dollar",
        "code": "AUD"
    },
    "time_zone": {
        "name": "Australia/Brisbane",
        "offset": 10,
        "current_time": "2018-07-27 17:54:09.726+1000",
        "is_dst": false,
        "dst_savings": 0
    }
}


Timezone API

Timezone API provides timezone and related information for an IP address or a timezone. Timezone API can be called in different variations:

1. Pass a timezone as query parameter to get the timezone information. Here is an example call:

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


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

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


3. Pass an IPv4 or IPv6 address as query parameter to get the regional timezone information. Here is an example call:

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


4. You can call the timezone API only with the API key. It uses the calling machine?s IP address to return the regional timezone information. Here is an example call:

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


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


Timezone API Full Response

{
    "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
}


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. If you don't append https to the request url, we automatically redirect it to https endpoint in order to maintain end to end encryption.


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 hard limit of 50,000 requests per month on our Free plan and 100,000 requests for 7 days on trial accounts.