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 a 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 the client's IP address. We strongly discourage the use of API key in client-side Javascript as it will expose API key to the public. If you still need to take action on client IP address from the 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 the client. It's fine to use your API Key in mobile apps.

To get your API key, sign up for the 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 it's 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 the public. This endpoint does not require any API Key.

$ curl 'https://api.ipgeolocation.io/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 a query parameter to lookup geolocation.
# 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'
  1. Do not pass an IP address as a query parameter. When the IP address is not present, it returns the geolocation of the device/client which is calling it.
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY'
* IP address is always included in the API response
  1. Bulk IP Geolocation Lookup
    IPGeolocation API has the 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.
    To lookup geolocation for multiple IP addresses, send a POST request and pass the "ips" array as JSON data along with it.
$ 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

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 you require. 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 only
$ 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 the country name and country code with the ISO2 format
$ 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 time zone information of 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 local currency information of multiple IP Addresses
$ 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"
        }
    }
]

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.

# Get information about IP Location only
$ 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"
}

Remove the Unnecessary Fields/Objects

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 from the response
$ 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 only and exclude the 'ip' for multiple IP addresses
$ 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"
    }
]

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": "Australian 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 a query parameter to get the timezone information. Here is an example call:
$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&tz=America/Los_Angeles'
  1. 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'
  1. Pass an IPv4 or IPv6 address as a query parameter to get the regional timezone information. Here is an example call:
$ curl 'https://api.ipgeolocation.io/timezone?apiKey=API_KEY&ip=1.1.1.1'
  1. 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.io/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 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

IPGeolocation API is the solution to identify country code (ISO2 and ISO3 standard), country name, continent code, continent name, country capital, state/province, district, city, zip code, latitude and longitude of city, is country belongs to European Union, calling code, top level domain (TLD), languages, country flag, internet service provider (ISP), connection type, organization, geoname ID, currency code, currency name, time zone ID, time zone offset, current time in the time zone, is time zone in daylight saving time, and total daylight savings. IPGeolocation API SDKs are written to help you get up to speed with the IPGeolocation API.

Developers can use these IPGeolocation API SDKs for software and web projects related to, but not limited to:

  1. Display native language and currency
  2. Redirect based on the country
  3. Digital rights management
  4. Web log stats and analysis
  5. Auto-selection of country, state/province and city on forms
  6. Filter access from countries you do not do business with
  7. Geo-targeting for increased sales and click-through

The detailed documentation on how to use these SDKs is available on the other sections of this documentation.
IPGeolocation API SDKs for different languages are available on github. Feel free to help us improve these SDKs. These are the available SDKs: