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

Field Type Description Can be empty?
domain string Domain name that is used to lookup geolocation information. It is not returned if an IP address is used to query IP Geolocation API. Yes
ip string IP address that is used to lookup geolocation information. No
hostname string Hostname of the IP address used to query IP Geolocation API. No
continent_code string 2-letter code of the continent. No
continent_name string Name of the continent. No
country_code2 string Country code (ISO 3166-1 alpha-2) of the country. No
country_code3 string Country code (ISO 3166-1 alpha-3) of the country. No
country_name string Name of the country. No
country_capital string Name of the country’s capital. No
state_prov string Name of the state/province/region. Yes
district string Name of the district or county. Yes
city string Name of the city. Yes
zipcode string ZIP code of the place. Yes
latitude float Latitude of the place. No
longitude float Longitude of the place. No
is_eu boolean Is the country belong to European Union? No
calling_code string Calling code of the country. No
country_tld string Top-level domain of the country. No
languages string Comma-separated list of the languages’ codes, spoken in the country. No
country_flag string URL to get the country flag. No
geoname_id number Geoname ID of the place from geonames.org No
isp string Name of the ISP holding the IP address. No
connection_type string Type of the connection, consuming the IP address. Yes
organization string Name of AS organization holding the IP address. Yes
asn string Autonomous system number of the autonomous system, to which IP address belongs to. Yes
currency.code string Currency code (ISO 4217). No
currency.name string Currency name (ISO 4217). No
currency.symbol string Currency symbol. No
time_zone.name string Name (ISO 8601) of the time zone. No
time_zone.offset number Time zone offset from UTC. No
time_zone.current_time string Current time in ‘yyyy-MM-dd HH:mm:ss.SSS+ZZZ’ format. No
time_zone.current_time_unix float Current time in seconds since 1970. No
time_zone.is_dst boolean Is the time zone in daylight savings? No
time_zone.dst_savings number Total daylight savings. No
security.threat_score number IP address’ threat score. It ranges from 0 to 100.
100 indicates highest threat and vice versa for lower score.		 No
security.is_tor boolean Indicates if the IP address is being consumed on a Tor endpoint. No
security.is_proxy boolean Indicates if the IP address belongs to a proxy network. No
security.proxy_type string Type of the proxy network if the IP address belongs to a proxy network. Yes
security.is_anonymous boolean Indicates if the IP address is being used anonymously. No
security.is_known_attacker boolean Indicates if the IP address is enlisted as an attacking IP address. No
security.is_cloud_provider boolean Indicates if the IP address belongs to a cloud provider (computing infrastructure providers). No
user_agent.userAgentString string User-Agent string passed along with the query in the User-Agent header. No
user_agent.name string User-Agent Name. No
user_agent.type string User-Agent Class. No
user_agent.version string User-Agent Version. No
user_agent.versionMajor string User-Agent Version Major. No
user_agent.device.name string Device Name. No
user_agent.device.type string Device Type. No
user_agent.device.brand string Device Brand. No
user_agent.device.CPU string Device CPU Model. No
user_agent.engine.name string Layout Engine Name. No
user_agent.engine.type string Layout Engine Class. No
user_agent.engine.version string Layout Engine Version. No
user_agent.engine.versionMajor string Layout Engine Version Major. No
user_agent.operatingSystem.name string Operating System Name. No
user_agent.operatingSystem.type string Operating System Class. No
user_agent.operatingSystem.version string Operating System Version. No
user_agent.operatingSystem.versionMajor string Operating System Version Major. No

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:

HTTP Status Description
401 It is returned for one of the following reasons:
(1) If API key (as 'apiKey' URL parameter) is missing from the request to IP Geolocation API.
(2) If an invalid (a random value) API key is provided.
(3) If the API request is made from an unverified ipgeolocation.io account.
(4) If your account has been disabled or locked to use by the admin due to abuse or illegal activity.
(5) When the request to IP Geolocation API is made using API key for a database subscription.
(6) When the request to IP Geolocation API is made on the 'paused' subscription.
(7) If you’re making API requests after your subscription trial has been expired.
(8) If your active until date has passed and you need to upgrade your account.
(9) If bulk IP to geolocation look-ups endpoint is called using free subscription API key.
(10) If user-agent lookup using custom string or bulk user-agent look-ups endpoints are called using free subscription API key.
(11) When the wrong input is provided in the request to any endpoint of IP Geolocation API.
403 It is returned for one of the following reasons:
(1) If IP to geolocation look-up for a domain name is done using a free subscription API key.
404 It is returned for one of the following reasons:
(1) If the queried IP address or domain name is not found in our database.
423 If the queried IP address is a [bogon]() (bogus IP address from the bogon space) IP address.
429 It is returned for one of the following reasons:
(1) If the API usage limit has reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'.
(2) If the surcharge API usage limit has reached against the subscribed plan.