IP Geolocation API

IP Geolocation API can be used to get real-time and accurate geolocation for any IP address. You can geolocate your online visitors and provide them customized experience accordingly.

We provide two endpoints in our GeoIP API. You can get the geolocation for an IP address in three different ways.

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-12-06 00:28:40.339-0800",
        "current_time_unix": 1544084920.339,
        "is_dst": false,
        "dst_savings": 1
    }
}

Single IP Lookup 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 geolocation for an IPv4 IP Address = 1.1.1.1
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1'

# Get geolocation for an 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 can be ommitted.

Response in Multiple Languages

The geolocation information for an IP address from the IP Geolocation API can be retreived in the following languages:

  • English (en)
  • German (de)
  • Russian (ru)
  • Japanese (ja)
  • French (fr)
  • Chinese Simplified (cn)
  • Spanish (es)
  • Czech (cs)
  • Italian (it)

By default, the API responds in English. You can change the response language by passing the language code as a query parameter lang. Here are a few curl examples:

# Get geolocation for an IPv4 IP Address = 1.1.1.1 in Chinese language
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&lang=cn'

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

Only the paid plan subscriptions can get the response in languages other than English. All the other users will only get the response in English.

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 Only 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": "America/Los_Angeles",
        "offset": -8,
        "current_time": "2018-12-06 00:28:40.339-0800",
        "current_time_unix": 1544084920.339,
        "is_dst": false,
        "dst_savings": 1
    }
}

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 'https://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 (except IP address) 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 and, 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"
}