Introduction

Our IP Geolocation API gives you a bunch of information from just an IP Address only. Here is a sample response from an IP Address.


{
    "ip": "33.33.33.33",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "country_capital": "Washington",
    "state_prov": "Ohio",
    "district": "Franklin County",
    "city": "Columbus",
    "zipcode": "43218",
    "latitude": "39.9747",
    "longitude": "-82.8948",
    "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": "DoD Network Information Center",
    "connection_type": "wired",
    "organization": "DoD Network Information Center",
    "geoname_id": "4510575",
    "currency": {
        "name": "Dollar",
        "code": "USD"
    },
    "time_zone": {
        "name": "America/New_York",
        "offset": "-4",
        "is_dst": true,
        "current_time": "2018-05-14 15:54:13.975-0400"
    }
}


API Key

In order to use our API, you need to get an API key which has to be passed as query parameter to API endpoint for authentication purpose. All of our endpoints require an API key to respond successfully to your requests except the one which sends back client's IP address. We strongly discourage the use of API key in client side javascript as it will expose this 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 API Key) and use that information in your backend to query our API from the code which is not exposed to client. Its fine to use your API Key in mobile apps.


To get an API Key, sign up for a desired plan. All of our paid plans come with free 7 day 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 request limits.


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


Get IP Endpoint

This endpoint just 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 pass it to geolocation endpoint so that your API Key is not exposed to public. This endpoint does not require any API Key.


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


Geolocation Endpoint

Geolocation endpoint has two forms. One which requires IP address to be passed as query parameter and the one which does not require IP to be passed as parameter. When IP is not passed, it takes IP address of device / client which is calling it.


Here is the example of how to call this endpoint.

$ curl ?https://api.ipgeolocation.io/ipgeo?apiKey=YOUR_API_KEY?


Here is an example of API call which requires you to pass an IPv4 or IPv6 IP address.

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

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

* IP address is always included in the response


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 to https endpoint in order to maintain end to end encryption.


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


Filter Responses

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

# Get information about city only
$ curl 'api.ipgeolocation.io/ipgeo?ip=1.1.1.1&fields=city&apiKey=API_KEY'
{
    ?ip?: ?1.1.1.1?,
    ?city?: ?South Brisbane?
}

# Get information about country name and country code with ISO2 format
$ curl 'api.ipgeolocation.io/ipgeo?ip=1.1.1.1&fields=country_code2,country_name&apiKey=API_KEY'
{
    "ip": "1.1.1.1",
    ?country_code2?: ?AU?,
    ?country_name?: ?Australia?
}

# Get information about local currency of the IP Address
$ curl 'api.ipgeolocation.io/ipgeo?ip=1.1.1.1&fields=currency&apiKey=API_KEY'
{
    "ip": "1.1.1.1",
    "currency": {
        "name": "Dollar",
        "code": "AUD"
    }
}


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

# Get information about IP Location only
$ curl 'api.ipgeolocation.io/ipgeo?ip=1.1.1.1&fields=geo&apiKey=API_KEY'
{
    "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"
}


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.