API Documentation
ipdataapi provides an easy-to-use API interface allowing customers to look various pieces of information IPv4 addresses are associated with. For each IP address processed, the API returns more than 9 unique data points, such as location data, connection data, languages data. The API is REST-based, lookup requests are made using straightforward HTTP POST URLs and results are returned in lightweight JSON or XML OR CSV OR Newline format within a matter of a few milliseconds. This API documentation will outline in detail the API's specification, access and features. At the very bottom you will find code examples in different programming languages. In case any technical questions are left unanswered, please feel free to contact with us.
Specs & Overview
API Access Key & Authentication
After creating an account, you will be assigned a API access key, that will allow you to authenticate with the API interface. To do this, simply append your API access key to the API's request body using the accesskey parameter. Find below an example API response for an IPv4 address in Singapore.
https://location.ipdataapi.com/v1.0/geolocation/json
{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}
Keep your API access key safe:
Your API access key is private and should at no time be shown publicly. You can reset it with immediate effect using your account dashboard at any given time.
API Response
Following a successful API request, the API will return more than 22 unique response objects containing result data. An API response can be returned in JSON or XML OR CSV OR Newline format and is structured into 4 modules: Location data, time zone data,Asn data and Proxy data. Response objects contained in each module will be explained in detail in the API Response Objects section.
Example API Response:
{
"cityname": "Singapore",
"connection": {
"asnname": "WHG Hosting Services Ltd",
"asnnumber": "204800",
"cityname": "Singapore",
"countrycode": "SG",
"countryname": "Singapore",
"ispdomain": "worldhost.group",
"ispname": "WHG Hosting Services Ltd",
"isptype": "DCH",
"network": "192.250.235.0/24",
"regionname": "Singapore"
},
"countrycode": "SG",
"countryname": "Singapore",
"ipaddress": "192.250.235.93",
"latitude": "1.289987",
"longitude": "103.850281",
"message": "success",
"regionname": "Singapore",
"responsecode": "200",
"status": "success",
"timezone": "+08:00",
"zipcode": "178958"
}
API Response Objects:
Looking for details about the response objects returned by the API? All available response objects are explained in detail in the API Response Objects section.API Endpoints
The API comes with a total of 1 available API endpoints. Please find below a quick overview and click on the endpoints to learn more about its usage.
Standard Lookup
Look up any given IP address.
API Error Codes
In the event that your API request fails for any reason, the API will return a JSON error message detailing information about the error that occurred. As an example, find below an error the API responds with if the limit of daily API requests has been reached.
Example Error:
{
"message": "Maximum Request Exceed.",
"responsecode": "403",
"status": "failed"
}
Common API Errors:
| Error Code | Error Description |
|---|---|
| 401 | User Not Active |
| 402 | Invalid accesskey |
| 403 | Maximum Request Exceed |
| 404 | IP address information not found |
| 405 | Invalid response format |
Standard IP Lookup
To look up a single IP address of your choice, simply append an IPv4 address to the API's base URL. Below you will find an example API request, required parameters and an example API response.
Example API Request:
https://location.ipdataapi.com/v1.0/geolocation/json
{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}
Request Parameters:
Object Description
ipaddr [Required] An IPv4 address of your choice.
accessKey [Required] Your API access key, available in your account dashboard.
Example API Response:
{
"cityname": "Singapore",
"connection": {
"asnname": "WHG Hosting Services Ltd",
"asnnumber": "204800",
"cityname": "Singapore",
"countrycode": "SG",
"countryname": "Singapore",
"ispdomain": "worldhost.group",
"ispname": "WHG Hosting Services Ltd",
"isptype": "DCH",
"network": "192.250.235.0/24",
"regionname": "Singapore"
},
"countrycode": "SG",
"countryname": "Singapore",
"ipaddress": "192.250.235.93",
"latitude": "1.289987",
"longitude": "103.850281",
"message": "success",
"regionname": "Singapore",
"responsecode": "200",
"status": "success",
"timezone": "+08:00",
"zipcode": "178958"
}
API Response Objects:
Looking for details about the response objects returned by the API? All available response objects are explained in detail in the API Response Objects section.
API Response Object
Based on which plan you are subscribed to and the options you specify for your API request, there are about 22 unique response objects the API is capable of responding with. Find below a complete list of API response objects:
Response Object Description :
| Response Object | Description |
|---|---|
| ipaddress | Returns the IP address as requested. |
| countrycode | Returns the 2-letter country code associated with the IP address. |
| countryname | Returns the country name associated with the IP address. |
| regionname | Returns the region name associated with the IP address. |
| cityname | Returns the city name associated with the IP address. |
| latitude | The approximate latitude of the location associated with the IP address. |
| longitude | The approximate longitude of the location associated with the IP address. |
| zipcode | Returns the zip code associated with the IP address. |
| timezone | Returns the time zone associated with the IP address. |
| asnname | Returns asnname (Autonomous System Name) associated with the IP address. |
| asnnumber | Returns asnnumber (Autonomous System Number) associated with the IP address. |
| cidr Returns | cidr (Classless Inter-Domain Routing) associated with the IP address. |
| cityname | Returns the proxy city name associated with the IP address. |
| countrycode | Returns the proxy 2-letter country code associated with the IP address. |
| countryname | Returns the proxy country name associated with the IP address. |
| ispcomname | Returns the proxy isp name associated with the IP address. |
| ispdomain | Returns the proxy isp domain name associated with the IP address. |
| ispusagetype | Returns the proxy isp type associated with the IP address. |
| regionname | Returns the proxy region name associated with the IP address. |
JSON Response Format
The API is capable of delivering API results in JSON format.
The API base path is
https://location.ipdataapi.com/v1.0/geolocation/json
POST Request Body
{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}
{
"cityname": "Singapore",
"connection": {
"asnname": "WHG Hosting Services Ltd",
"asnnumber": "204800",
"cityname": "Singapore",
"countrycode": "SG",
"countryname": "Singapore",
"ispdomain": "worldhost.group",
"ispname": "WHG Hosting Services Ltd",
"isptype": "DCH",
"network": "192.250.235.0/24",
"regionname": "Singapore"
},
"countrycode": "SG",
"countryname": "Singapore",
"ipaddress": "192.250.235.93",
"latitude": "1.289987",
"longitude": "103.850281",
"message": "success",
"regionname": "Singapore",
"responsecode": "200",
"status": "success",
"timezone": "+08:00",
"zipcode": "178958"
}
XML Response Format
The API is capable of delivering API results in XML format.
The API base path is
https://location.ipdataapi.com/v1.0/geolocation/xml
POST Request Body
{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}
<?xml version="1.0" encoding="UTF-8" ?>
<info>
<status>success</status>
<message>success</message>
<responsecode>200</responsecode>
<ipaddress>192.250.235.93</ipaddress>
<countrycode>SG</countrycode>
<countryname>Singapore</countryname>
<regionname>Singapore</regionname>
<cityname>Singapore</cityname>
<latitude>1.289987</latitude>
<longitude>103.850281</longitude>
<zipcode>178958</zipcode>
<timezone>+08:00</timezone>
<connection>
<network>192.250.235.0/24</network>
<asnnumber>204800</asnnumber>
<asnname>WHG Hosting Services Ltd</asnname>
<countrycode>SG</countrycode>
<countryname>Singapore</countryname>
<regionname>Singapore</regionname>
<cityname>Singapore</cityname>
<ispname>WHG Hosting Services Ltd</ispname>
<ispdomain>worldhost.group</ispdomain>
<isptype>DCH</isptype>
</connection>
</info>
CSV Response Format
The API is capable of delivering API results in CSV format.
The API base path is
https://location.ipdataapi.com/v1.0/geolocation/csv
POST Request Body
{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}
success,success,200,192.250.235.93,SG,Singapore,Singapore,Singapore,1.289987,103.850281,178958,+08:00,192.250.235.0/24,204800,WHG Hosting Services Ltd,SG,Singapore,Singapore,Singapore,WHG Hosting Services Ltd,worldhost.group,DCH
status,message,responsecode,ipaddress,countrycode,countryname,regionname,cityname,latitude,longitude,zipcode,timezone,connection,network,asnnumber,asnname,countrycode,countryname,regionname,cityname,ispname,ispdomain,isptype
NEWLINE Response Format
The API is capable of delivering API results in NEWLINE format.
The API base path is
https://location.ipdataapi.com/v1.0/geolocation/newline
POST Request Body
{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}
success
success
200
192.250.235.93
SG
Singapore
Singapore
Singapore
1.289987
103.850281
178958
+08:00
192.250.235.0/24
204800
WHG Hosting Services Ltd
SG
Singapore
Singapore
Singapore
WHG Hosting Services Ltd
worldhost.group
DCH
status,
message,
responsecode,
ipaddress,
countrycode,
countryname,
regionname,
cityname,
latitude,
longitude,
zipcode,
timezone,
connection,
network,
asnnumber,
asnname,
countrycode,
countryname,
regionname,
cityname,
ispname,
ispdomain,
isptype
Python
Standard Lookup via Python
Find below a Python example making use of the Standard Lookup endpoint:
import requests
import json
url = "https://location.ipdataapi.com/v1.0/geolocation/json"
payload = json.dumps({
"accesskey": YOUR_ACCESS_KEY,
"ipaddr": "192.250.235.93"
})
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Php(Curl)
Standard Lookup via Php
Find below a Php example making use of the Standard Lookup endpoint:
'https://location.ipdataapi.com/v1.0/geolocation/json',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"accesskey":YOUR_ACCESS_KEY,
"ipaddr":"192.250.235.93"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
JavaScript
Standard Lookup via JavaScript
Find below a JavaScript example making use of the Standard Lookup endpoint:
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"accesskey": YOUR_ACCESS_KEY,
"ipaddr": "192.250.235.93"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://location.ipdataapi.com/v1.0/geolocation/json", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
JavaScript(jquery.ajax)
Standard Lookup via JavaScript
Find below a JavaScript example making use of the Standard Lookup endpoint:
var settings = {
"url": "https://location.ipdataapi.com/v1.0/geolocation/json",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({
"accesskey": YOUR_ACCESS_KEY,
"ipaddr": "192.250.235.93"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});