Our IP API provides geographical information about website visitors with any IPv4 or IPv6 address in JSON and XML format over a secure HTTPS connection even in our free plan. We provide data such as country name, country code, city, state, local currency, time zone, ISP, ASN, Company Details, device data from User-Agent String, VPN, Proxy, TOR and threat intelligence data. Our services are globally available with latency-based routing.
IP to Location module provides geolocation information related to an IP address such as continent, country, country capital, state/province, city, locality, accuracy radius, zip code, DMA code, country flag, latitude and longitude information.
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code2": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state_prov": "California",
"state_code": "US-CA",
"district": "Santa Clara",
"city": "Mountain View",
"locality": "Mountain View",
"accuracy_radius": "5",
"dma_code": "807",
"zipcode": "94043-1351",
"latitude": "37.42240",
"longitude": "-122.08421",
"is_eu": false,
"country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
"geoname_id": "6301403",
"country_emoji": "🇺🇸"
}
Country metadata module provides country calling (dialing) code, country's top level domain name (ccTLD) and official spoken languages in the country associated with the queried IP address.
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
]
}
Network information module provides network related information such as ASN details including AS number, organization name, country where the ASN is registered, type of ASN, Regional Internet Registry (RIR), number of IPv4 and IPv6 routes, and allocation status. It also includes company details such as the name of the company to whom the IP address is further licensed by the ISP, its type, and domain name, along with the connection type (wired or wireless).
"network": {
"asn": {
"as_number": "15169",
"organization": "Google LLC",
"country": "US",
"asn_name": "GOOGLE",
"type": "isp",
"domain": "about.google",
"date_allocated": "1997-09-15",
"allocation_status": "Assigned",
"num_of_ipv4_routes": "1099",
"num_of_ipv6_routes": "107",
"rir": "ARIN"
},
"company": {
"name": "Google LLC",
"type": "hosting",
"domain": "google.com"
},
"connection_type": "wired"
}
IP to Currency module provides currency information of the country such as currency name, currency symbol and currency code from an IP address.
"currency": {
"name": "US Dollar",
"code": "USD",
"symbol": "$"
}
The security module provides threat intelligence data such as threat score, is tor, vpn or proxy, proxy provider name, is known attacker, and if the IP address belongs to one of the cloud providers.
"security": {
"threat_score": 80,
"is_tor": false,
"is_proxy": true,
"proxy_type": "VPN",
"proxy_provider": "proton",
"is_anonymous": true,
"is_known_attacker": true,
"is_spam": false,
"is_bot": false,
"is_cloud_provider": false,
"cloud_provider": ""
}
The Abuse Module provides contact details of the responsible party for the queried IP address, including country, organization, email address and phone number. Ideal for reporting malicious activity or handling abuse complaints.
"abuse": {
"route": "78.8.0.0/14",
"country": "PL",
"handle": "NT1264-RIPE",
"name": "Netia Telekom S.A.",
"organization": "Netia Telekom S.A.",
"role": "abuse",
"kind": "group",
"address": "Poleczki 13\n02-822 Warszawa\nPoland",
"emails": [
"abuse@inetia.pl"
],
"phone_numbers": [
"+48(22)352 2213",
"+48(22)352 0000"
]
}
IP to Time Zone module provides time and timezone related information such as timezone name, UTC/GMT offset, current date and time, daylight saving time status, daylight saving offset in hours, along with start and end details of daylight saving time.
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -7,
"current_time": "2024-10-02 00:06:41.301-0700",
"current_time_unix": 1727852801.301,
"is_dst": true,
"dst_savings": 1,
"dst_exists": true,
"dst_start": {
"utc_time": "2024-03-10 TIME 10",
"duration": "+1H",
"gap": true,
"dateTimeAfter": "2024-03-10 TIME 03",
"dateTimeBefore": "2024-03-10 TIME 02",
"overlap": false
},
"dst_end": {
"utc_time": "2024-11-03 TIME 09",
"duration": "-1H",
"gap": false,
"dateTimeAfter": "2024-11-03 TIME 01",
"dateTimeBefore": "2024-11-03 TIME 02",
"overlap": true
}
}
User Agent module parses the browser user agent string and provides detailed device information such as device name, device version, device type, device operating system, device browser, browser engine and browser version. It can identify robots, crawlers and attackers.
"user_agent": {
"userAgentString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
"name": "Safari",
"type": "Browser",
"version": "13.0.5",
"versionMajor": "13",
"device": {
"name": "Apple Macintosh",
"type": "Desktop",
"brand": "Apple",
"cpu": "Intel"
},
"engine": {
"name": "AppleWebKit",
"type": "Browser",
"version": "605.1.15",
"versionMajor": "605"
},
"operatingSystem": {
"name": "Mac OS",
"type": "Desktop",
"version": "10.15.3",
"versionMajor": "10.15"
}
}
With reverse IP Lookup, you can resolve the host name or domain or router dns address. This gives you detailed information about the original source of traffic.
curl 'https://api.ipgeolocation.io/v2/ipgeo?include=hostname&ip=8.8.8.8&apiKey=API_KEY'
{
"ip":"8.8.8.8",
"hostname":"dns.google",
"..."
}
Enter the domain address in place of IP address and our API will perform a DNS Lookup to give you the information about the web hosting provider and the geographical location of the website.
{
"domain": "ipgeolocation.io",
"ip": "104.20.40.71",
"location": {
"country_name": "United States",
"state_prov": "California",
"city": "San Francisco",
"..."
},
"network": {
"asn": {
"as_number": "13335",
"domain": "cloudflare.com"
},
"company": {
"name": "Cloudflare, Inc."
}
}
}
Use our Bulk IP Lookup endpoint to perform batch lookup of multiple IP addresses in a single request. Query up to 50,000 IPv4, IPv6 or domain names at once.
curl -X POST 'https://api.ipgeolocation.io/v2/ipgeo-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ips": ["1.1.1.1", "1.2.3.4", "1.2.3.5", "1.2.3.6", "1.2.3.7"]
}'
You can retrieve the geolocation information for an IP address in the following languages:
Adapt the content of your website to the destination of your visitors. Make your visitors feel right at home by "talking" to them in their local language and connect with them instantly. With IP geolocation, redirect your users to their region-specific websites and increase the possibility of increasing conversions up to 70%.
Do you have an awesome content localization strategy in place? IP geolocation is a non-intrusive way to know where your visitors are coming from. Don't ruin your visitor's website experience by showing annoying pop-ups asking for their location. Our geolocation API will detect their location from their IP address and show them the relevant message.
Enforce digital rights of your content using IP location API. Build a virtual fence around your content and make sure that only the people inside the fence can see it.
With our security and user agent module, you can identify anonymous traffic sources, known attackers, suspicious devices and tor nodes to prevent online fraud, trial abusers, forum spams and botnet attackers.
IP Geolocation API provides real-time and accurate geolocation, network, abuse, 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 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/v2/ipgeo and its full JSON response is below:
In order to find geolocation information about an IP address or a domain name, pass
it as a query parameter
ip
like below.
Note that apiKey
is also needed to be passed as a query parameter for authorization. This endpoint is
meant to be called from the server side.
Here's an example to get the geolocation information for '8.8.8.8'.
Here's an example to get the geolocation information for '2001:4860:4860::1'.
Here's an example to get the geolocation information for 'dns.google.com'.
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.
Note:
apiKey
parameter can also be ommitted from your API request when this
endpoint is called from client side using
Request Origin.
This feature is available only on our paid API subscriptions (STANDARD or ADVANCED). This endpoint allows you to perform the geolocation lookup for multiple IPv4, IPv6 addresses or domain names (maximum 50,000) 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 to query the geolocation data for multiple IPs at once.
The geolocation information for an IP address from the IP Geolocation API can be retrieved in the following languages
By default, the API responds in English. You can change the
response language by passing the language code as a query
parameter
lang
. Here
is an example to get the geolocation data for IP adderss
'1.1.1.1' in Chinese language:
Only the paid plan subscriptions (STANDARD or ADVANCED) can get the response in languages other than English. All the other subscriptions will only get the response in English.
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:
First, you can filter the API response by specifying the fields that you need,
instead of getting the full response. To do this, pass the desired field names
using the fields
query parameter,
with each field represented as a dot-separated path.
Here are a few examples to get only the required fields:
You can use our filters with Bulk IP Lookup as well. Here is an example:
Second, you can also filter the API response by excluding specific fields (except the
IP address) that you don't need. To do this, pass the unwanted field names using the
excludes
query parameter, with each
field represented as a dot-separated path. Here's an example showing how to exclude
unnecessary fields:
Third, You can combine the fields
and excludes
query parameters to create fully
customized API responses. This approach allows you to retrieve only the data you need while
minimizing response size and latency. Here's a sample code to demonstrate how to use both
parameters effectively:
IP Geolocation API also provides IP-Security information on Advanced API subscription,
but doesn't respond it by default. To get IP-Security information along with the 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:
IP Geolocation API can also provide abuse contact information of an IP address on Advanced API
subscription, but doesn't respond it by default. To get abuse contact information along with
the geolocation information, you must pass the
include=abuse
as a query parameter in the URL.
Here is an example of an IP Geolocation lookup that includes abuse contact information, along with the country and city associated with the IP address:
If you want to get DMA (Designated Market Area) code, which is specifically used in the US for
marketing and regional targeting, you can get through the IP Geolocation API on Advanced
API subscription. To get DMA code along with the geolocation information, you must pass the
include=dma
as a query parameter in the URL.
Here is an example of an IP Geolocation lookup that includes dma code, along with the location information associated with the IP address:
IPGeolocation API also provide hostname lookup for an IP address
on all the paid API subscriptions (STANDARD and ADVANCED), 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:
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.
IP Geolocation API can also provide time zone information for an IP address on paid API plans
(STANDARD and ADVANCED). However, this data is not included in the response by default.
To get the time zone information along with the geolocation information, you must need to
pass the
include=time_zone
as a query parameter in the URL.
Here is an example of an IP Geolocation lookup that includes time zone data, along with the country information associated with the IP address:
IP Geolocation API also provides User-Agent information of the
client 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=user_agent
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, along with city and country name associated with the IP Address:
Note: To
get hostname, DMA code, IP-Security information, Abuse contact Information, Time Zone
Information and user-agent information together for an IP address and the device, you can
pass
include=hostname, dma, security, abuse, time_zone, user_agent
as a query
parameter in the URL.
Below, we provide separate tables for each JSON object in the response, listing all possible fields available across all plans. The fifth column indicates the minimum plan required to access each field.
Please note that field availability is cumulative: all fields available in the BASIC plan are also included in STANDARD and ADVANCED, and all STANDARD fields are also available in the ADVANCED plan.
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
ip | string | IP address that is used to lookup geolocation information. | No | BASIC |
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 | STANDARD |
hostname | string | Hostname of the IP address used to query IP Geolocation API. | No | STANDARD |
location
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
continent_code | string | 2-letter code of the continent. | No | BASIC |
continent_name | string | Name of the continent. | No | BASIC |
country_code2 | string | Country code (ISO 3166-1 alpha-2) of the country. | No | BASIC |
country_code3 | string | Country code (ISO 3166-1 alpha-3) of the country. | No | BASIC |
country_name | string | Name of the country. | No | BASIC |
country_name_official | string | Official name (ISO 3166) of the country. | No | BASIC |
country_capital | string | Name of the country’s capital. | No | BASIC |
state_prov | string | Name of the state/province/region. | Yes | BASIC |
state_code | string | Code of the state/province/region. | Yes | BASIC |
district | string | Name of the district or county. | Yes | BASIC |
city | string | Name of the city. | Yes | BASIC |
locality | string | A more specific area in city or it can be same as city. | Yes | ADVANCED |
accuracy_radius | string | Circular radius in Km, where the IP address location can be found. | Yes | ADVANCED |
dma_code | string | Representing Designated Market Area (DMA) code specifically used in the United States for media marketing. | Yes | BASIC |
zipcode | string | ZIP/Postal code of the place. | Yes | BASIC |
latitude | string | Latitude of the place. | No | BASIC |
longitude | string | Longitude of the place. | No | BASIC |
is_eu | boolean | Is the country belong to European Union? | No | BASIC |
country_flag | string | URL to get the country flag. | No | BASIC |
geoname_id | string | Geoname ID of the place from geonames.org | Yes | BASIC |
country_emoji | string | Emoji of the Country flag. | Yes | BASIC |
country_metadata
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
calling_code | string | Calling code/Dialing code of the country. | No | BASIC |
tld | string | Top Level Domain Name (TLD) of the country, which is also called ccTLD. | No | BASIC |
languages | list of strings | List of the languages’ codes, spoken in the country. | No | BASIC |
network
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
asn.as_number | string | Autonomous system number of the autonomous system, to which IP address belongs to. | Yes | STANDARD |
asn.organization | string | Legal Full Name of AS organization holding the IP address. | Yes | STANDARD |
asn.country | string | Name of the country, ASN is residing. | Yes | STANDARD |
asn.asn_name | string | Name associated with the Autonomous System, usually representing organization. | Yes | ADVANCED |
asn.type | string | Type of the ASN, whether ISP, Business, etc. | Yes | ADVANCED |
asn.domain | string | Domain name associated with the ASN holding the IP address. | Yes | ADVANCED |
asn.date_allocated | string | Last date, when the IP address assigned to the ASN. e.g., in format '1st June 2001' | Yes | ADVANCED |
asn.allocation_status | string | Whether the IP address is currently assigned to the ASN or not. | Yes | ADVANCED |
asn.num_of_ipv4_routes | string | Total number of IPv4 routes, held by the ASN. These Routes can be queried from our ASN API. | Yes | ADVANCED |
asn.num_of_ipv6_routes | string | Total number of IPv6 routes, held by the ASN. These Routes can be queried from our ASN API. | Yes | ADVANCED |
asn.rir | string | Name of the Regional Internet Registry(RIR) that allocated the AS number. | Yes | ADVANCED |
company.name | string | Name of the company/ISP holding the IP address. | No | STANDARD |
company.type | string | Type of the company whether is an ISP, hosting provider or business, etc. | Yes | ADVANCED |
company.domain | string | Official domain name used by the company. | Yes | ADVANCED |
connection_type | string | Type of the connection, consuming the IP address. | Yes | ADVANCED |
currency
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
code | string | Currency code (ISO 4217). | No | BASIC |
name | string | Currency name (ISO 4217). | No | BASIC |
symbol | string | Currency symbol. | No | BASIC |
security
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
threat_score | number | IP address’ threat score. It ranges from 0 to 100. 100 indicates highest threat and vice versa for lower score. | No | ADVANCED |
is_tor | boolean | Indicates if the IP address is being consumed on a Tor endpoint. | No | ADVANCED |
is_proxy | boolean | Indicates if the IP address belongs to a proxy network. | No | ADVANCED |
proxy_type | string | Type of the proxy network if the IP address belongs to a proxy network. | Yes | ADVANCED |
proxy_provider | string | Name of the proxy provider, if the IP address belongs to a proxy network. | Yes | ADVANCED |
is_anonymous | boolean | Indicates if the IP address is being used anonymously. | No | ADVANCED |
is_known_attacker | boolean | Indicates if the IP address is enlisted as an attacking IP address. | No | ADVANCED |
is_spam | boolean | Indicates if the IP address is enlisted as a spam IP address. | No | ADVANCED |
is_bot | boolean | Indicates if the IP address is enlisted as a bot IP address. | No | ADVANCED |
is_cloud_provider | boolean | Indicates if the IP address belongs to a cloud provider (computing infrastructure providers). | No | ADVANCED |
cloud_provider | boolean | Name of the Cloud Provider, if the IP address belongs to a cloud provider. | Yes | ADVANCED |
abuse
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
route | string | Network route associated with the IP address. | Yes | ADVANCED |
country | string | Country where the responsible entity is located. | Yes | ADVANCED |
handle | string | Abuse handle or ID found in WHOIS or RDAP records. | Yes | ADVANCED |
name | string | Name of the abuse contact person or entity.. | Yes | ADVANCED |
organization | string | Organization responsible for the IP address. | Yes | ADVANCED |
role | string | Role of the contact (e.g., abuse, administrative, registrant, etc.). | Yes | ADVANCED |
kind | string | Type of contact: individual, team, or organization. | Yes | ADVANCED |
address | string | Physical mailing address of the responsible entity.. | Yes | ADVANCED |
emails | list of strings | Email address(es) of the abuse contact. | Yes | ADVANCED |
phone_numbers | list of strings | Phone number(s) in international format for the abuse contact. | Yes | ADVANCED |
time_zone
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
name | string | Name (ISO 8601) of the time zone. | No | STANDARD |
offset | number | Time zone offset from UTC. | No | STANDARD |
offset_with_dst | number | Time zone with DST offset from UTC. | No | STANDARD |
current_time | string | Current time in ‘yyyy-MM-dd HH:mm:ss.SSS±ZZZ’ format. | No | STANDARD |
current_time_unix | float | Current time in seconds since 1970. | No | STANDARD |
is_dst | boolean | Is the time zone in daylight savings? | No | STANDARD |
dst_savings | number | Total daylight savings. | No | STANDARD |
dst_exists | boolean | Whether Daylight Saving Time (DST) is observed in the region. | No | STANDARD |
dst_start.utc_time | string | The date and time in UTC when DST begins. | No | STANDARD |
dst_start.duration | string | The time change that occurs when DST starts. | No | STANDARD |
dst_start.gap | boolean | Is there a gap when the clocks jump forward or not. | No | STANDARD |
dst_start.dateTimeAfter | string | The local date and time that immediately follows the start of DST. | No | STANDARD |
dst_start.dateTimeBefore | string | The local date and time immediately before DST begins. | No | STANDARD |
dst_start.overlap | boolean | Whether there is an overlap of time due to clocks being set back when DST starts. | No | STANDARD |
dst_end.utc_time | string | The date and time in UTC when DST ends. | No | STANDARD |
dst_end.duration | string | The time change that occurs when DST ends. | No | STANDARD |
dst_end.gap | boolean | Is there a gap when the clocks jump backward or not. | No | STANDARD |
dst_end.dateTimeAfter | string | The local date and time that immediately follows the ends of DST. | No | STANDARD |
dst_end.dateTimeBefore | string | The local date and time immediately before DST ends. | No | STANDARD |
dst_end.overlap | boolean | Whether there is an overlap of time due to clocks being set back when DST ends. | No | STANDARD |
user_agent
json object reference
Field | Type | Description | Can be empty? | Availability |
---|---|---|---|---|
user_agent_string | string | User-Agent string passed along with the query in the 'User-Agent' header. | No | STANDARD |
name | string | User-Agent Name. | No | STANDARD |
type | string | User-Agent Class. | No | STANDARD |
version | string | User-Agent Version. | No | STANDARD |
version_major | string | User-Agent Version Major. | No | STANDARD |
device.name | string | Device Name. | No | STANDARD |
device.type | string | Device Type. | No | STANDARD |
device.brand | string | Device Brand. | No | STANDARD |
device.cpu | string | Device CPU Model. | No | STANDARD |
engine.name | string | Layout Engine Name | No | STANDARD |
engine.type | string | Layout Engine Class | No | STANDARD |
engine.version | string | Layout Engine Version. | No | STANDARD |
engine.version_major | string | Layout Engine Version Major. | No | STANDARD |
operating_system.name | string | Operating System Name. | No | STANDARD |
operating_system.type | string | Operating System Class. | No | STANDARD |
operating_system.version | string | Operating System Version. | No | STANDARD |
operating_system.version_major | string | Operating System Version Major. | No | STANDARD |
operating_system.build | string | Operating System Version Major. | No | STANDARD |
For all possible values of the User Agent type fields, please check here.
IP Geolocation API returns HTTP status code 200 for a successful API request along with the response.
While, in case of a bad or invalid request, IP Geolocation API returns 4xx HTTP status code along with a descriptive message explaining the reason for the error.
Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions:
HTTP Status | Description |
---|---|
400 Bad Request |
It is returned for one of the following reasons:
|
401 Unauthorized |
It is returned for one of the following reasons:
|
403 Forbidden |
|
404 Not Found |
It is returned for one of the following reasons:
|
405 Method Not Allowed |
|
413 Content Too Large |
|
415 Unsupported Media Type |
|
423 Locked |
|
429 Too Many Requests |
It is returned for one of the following reasons:
|
499 Client Closed Request |
|
5XX Server Side Error |
|
To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.
Our SDKs are also available on Github. Feel free to help us improve them. Following are the available SDKs: