IP Geolocation API

IP Geolocation API provides real-time and accurate geolocation, and security information for any IPv4 or IPv6 address and domain name along with the user-agent detail for the provided user-agent string. You can geolocate your online visitors and provide them the customized user-experience accordingly.

We provide the two endpoints in our IP Lookup API to get geolocation information.

Single IP Geolocation Lookup API

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

{
    "ip": "8.8.8.8",
    "hostname": "dns.google",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "country_capital": "Washington, D.C.",
    "state_prov": "California",
    "district": "Santa Clara",
    "city": "Mountain View",
    "zipcode": "94043-1351",
    "latitude": "37.42240",
    "longitude": "-122.08421",
    "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",
    "geoname_id": "6301403",
    "isp": "Google LLC",
    "connection_type": "",
    "organization": "Google LLC",
    "asn": "AS15169",
    "currency": {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$"
    },
    "time_zone": {
        "name": "America/Los_Angeles",
        "offset": -8,
        "current_time": "2020-12-17 07:49:45.872-0800",
        "current_time_unix": 1608220185.872,
        "is_dst": false,
        "dst_savings": 1
    }
}

Passing an IPv4, IPv6 Address or a domain

In order to find geolocation information about an IP address or a domain name, 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 = 8.8.8.8
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8'

# 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'

# Get geolocation for a domain name = google.com
$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=dns.google.com

Without Passing an IP Address

When this endpoint is queried without an IP address, 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: apiKey parameter can also be ommitted from your API request when this endpoint is called from client side using Request Origin.

Bulk IP Geolocation Lookup API

This feature is available only on the paid API subscriptions. This endpoint allows you to perform the geolocation lookup for multiple IPv4, IPv6 addresses or domain names (maximum 50) at the same time. The requests count per lookup is equal to total IP addresses or domain names 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"] }'

Response in Multiple Languages

The geolocation information for an IP address from the IP Geolocation API can be retrieved 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 subscriptions will only get the response in English.

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 you processing time, bandwidth and improve the API response time.

You can filter the API response in two ways:

Get the Required Fields Only

First, you can filter the API response by specifying names of the fields that you want instead of getting the full response. Names of the required fields 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 Country Name and Country Code (ISO2) Only

$ 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 Only

$ 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 Only 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

Second, you can also filter the API response by specifying the names of fields (except IP address) that you want to remove from the API response. Names of the fields 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"
}

IP-Security Information for an IP Address

IP Geolocation API also provides IP-Security information on all the paid subscriptions, but doesn't respond it by default. To get IP-Security information along with geolocation information, you must pass the include=security as a query parameter in the URL.

Here is an example to IP Geolocation lookup that includes IP security information for the IP address:

$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=198.90.78.238&fields=geo&include=security

{
    "ip": "198.90.78.238",
    "country_code2": "CA",
    "country_code3": "CAN",
    "country_name": "Canada",
    "state_prov": "Quebec",
    "district": "Sainte-Rose",
    "city": "Laval",
    "zipcode": "H7P 4W5",
    "latitude": "45.58160",
    "longitude": "-73.76980",
    "security": {
        "threat_score": 7,
        "is_tor": false,
        "is_proxy": true,
        "proxy_type": "VPN",
        "is_anonymous": true,
        "is_known_attacker": false,
        "is_cloud_provider": false
    }
}

Hostname Lookup for an IP Address

IPGeolocation API also provide hostname lookup for an IP address on all the paid subscriptions, but doesn't respond it by default. To get the hostname for an IP address, you can pass one of the three values (hostname, liveHostname, hostnameFallbackLive) as a URL parameter (include).

Here is an example to IP Geolocation lookup that includes hostname for the IP address:

$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=geo&include=liveHostname'

{
    "ip": "1.1.1.1",
    "hostname": "one.one.one.one",
    "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"
}

include=hostname URL Parameter

This URL parameter enables the IPGeolocation API to lookup hostname from our IP-Hostname database and returns the same IP address if there is no hostname found for the queried IP address. Lookup thru IP-Hostname database is faster than other options but is experimental and under process and can produce unwanted output.

include=liveHostname URL Parameter

This URL parameter enables the IPGeolocation API to lookup hostname from live sources. Lookup thru live sources is accurate but can introduce more latency to your query to IPGeolocation API.

include=hostnameFallbackLive URL Parameter

This URL parameter enables the IPGeolocation API to lookup hostname from our IP-Hostname database and if there is no hostname found for the queried IP address, then lookup thru the live sources. This option has been introduced for faster and accurate lookup.

User-Agent Information for a Device

IP Geolocation API also provides User-Agent information on all the paid subscriptions, but doesn't respond it by default. To get User-Agent information along with the geolocation information, you must pass the include=useragent as a query parameter in the URL.

Here is an example to IP Geolocation lookup that includes User-Agent information for a device from which the query originated:

$ curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=geo&include=useragent

{
    "ip": "1.1.1.1",
    "country_code2": "AU",
    "country_code3": "AUS",
    "country_name": "Australia",
    "state_prov": "Queensland",
    "district": "South Brisbane",
    "city": "Brisbane",
    "zipcode": "4101",
    "latitude": "-27.47561",
    "longitude": "153.01537",
    "user_agent": {
        "userAgentString": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
        "name": "Chrome",
        "type": "Browser",
        "version": "51.0.2704.103",
        "versionMajor": "51",
        "device": {
            "name": "Linux Desktop",
            "type": "Desktop",
            "brand": "Unknown",
            "CPU": "Intel x86_64"
        },
        "engine": {
            "name": "Blink",
            "type": "Browser",
            "version": "51.0",
            "versionMajor": "51"
        },
        "operatingSystem": {
            "name": "Linux",
            "type": "Desktop",
            "version": "Intel x86_64",
            "versionMajor": "Intel x86"
        }
    }
}

Note: To get hostname, IP-Security information, and user-agent information together for an IP address and the device, you can pass include=hostname,security,useragent as a query parameter in the URL.

Reference to IPGeolocation API Response

Error Codes

IP Geolocation API returns 200 HTTP status for a successful API request along with the response.

While, in case of a bad or illegal request, IP Geolocation API returns 4xx HTTP code along with a descriptive message as why the error occured.

Here is the description of why a specific HTTP code is returned: