IP Geolocation API

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

We provide 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 IPv4 or IPv6 address 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": "google-public-dns-a.google.com",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "country_capital": "Washington",
    "state_prov": "California",
    "district": "",
    "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": {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$"
    },
    "time_zone": {
        "name": "America/Los_Angeles",
        "offset": -8,
        "current_time": "2019-01-14 03:30:00.135-0800",
        "current_time_unix": 1547465400.135,
        "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 = 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'

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

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.

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"] }'

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 users 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 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 must pass the include=hostname as a query parameter in the URL.

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=hostname'

{
    "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"
}

Note: To get IP-Security information and hostname together for an IP address, you can pass include=hostname,security 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/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

Error Codes

IP Geolocation API returns 200 HTTP status in case of a successful request.

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

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

HTTP Status Description
400 If your subscription is paused from use.
401 It is returned for one of the following reasons:
(1) If the provided API key is not valid.
(2) If your account has been disabled or locked by admin because of any illegal activity.
(3) If you’re making requests after your subscription trial has been expired.
(4) If you’ve exceeded your requests limit.
(5) If your subscription is not active.
(6) If you’re accessing a paid feature on free subscription.
(7) If you’re making a request without authorization with our IP Geolocation API.
403 If the queried IP address or domain name is not valid.
404 If the queried IP address or domain name is not found in our database.
423 If the queried IP address is a bogon (reserved) IP address like private, multicast, etc.