Introduction
IP Doctor offers a powerful, real-time IP to geolocation API capable of looking up accurate location data and assessing security threats originating from risky IP addresses. Results are delivered within milliseconds in JSON or XML format. Using the ipdoctor API you will be able to locate website visitors at first glance and adjust your user experience and application accordingly.
This documentation outlines in detail API features, available options and integration guides in different programming languages.
Getting Started
API Access Key
Your API Access Key is your unique authentication key used to gain access to the IP Doctor API. In order to authenticate with the API, append the access_key parameter to the API's base URL and set it to your access key value.
Base URL:
https://api.ipdoctor.net/
Append your API Access Key: Here is an example API call illustrating how to authenticate with the IP Doctor API:
https://api.ipdoctor.net/134.201.250.155
? 'access_key' = YOUR_ACCESS_KEY
API Response
The ipdoctor API is capable of delivering data either in JSON format (default) or XML format. Find below the API result ipdoctor would return in response to the API call shown in the section above, which queries the API for the IP address 134.201.250.155.
API Response
{
"ip": "134.201.250.155",
"hostname": "134.201.250.155",
"type": "ipv4",
"continent_code": "NA",
"continent_name": "North America",
"country_code": "US",
"country_name": "United States",
"region_code": "CA",
"region_name": "California",
"city": "Los Angeles",
"zip": "90013",
"location": {
"geoname_id": 5368361,
"capital": "Washington D.C.",
"languages": [
{
"code": "en",
"name": "English",
"native": "English"
}
],
"country_flag_emoji": "🇺🇸",
"calling_code": "1",
"is_eu": false,
"latitude": 34.0453,
"longitude": -118.2413,
},
"time_zone": {
"id": "America/Los_Angeles",
"current_time": "2018-03-29T07:35:08-07:00",
"gmt_offset": -25200,
"code": "PDT",
"is_daylight_saving": true
},
"currency": {
"code": "USD",
"name": "US Dollar",
"plural": "US dollars",
"symbol": "$",
"symbol_native": "$"
},
"connection": {
"asn": 25876,
"isp": "Los Angeles Department of Water & Power"
},
"security": {
"is_proxy": false,
"proxy_type": null,
"is_crawler": false,
"crawler_name": null,
"crawler_type": null,
"is_tor": false,
"blacklist_found": "1",
"date": "Mon, 08 Apr 19 04:25:51 +0000"
},
"check_id": "ea7fed05b4fe1e1b50df52711221d4e7"
}
API responses come with comprehensive location-related data, currency-related data, timezone-related data, connection-related data and security-related data. Throughout the Response Objects section you will learn more about the given response structure and its objects.
Available Endpoints
The ipdoctor API offers 3 different endpoints, each accepting a different set of parameters and returning different results. Click on the headings below to jump to the respective endpoint's description.
- Standard Lookup Look up the data behind an IP address.
- Requester Lookup Look up the data behind the IP address your API request is coming from.
Connecting via HTTPS
All premium subscription plans available for the ipdoctor API come with support for 256-bit SSL encryption. To connect to the API via HTTPS
, simply use the https protocol instead of standard http
.
JSONP Callbacks
Example Request: In our example request we are specifying the function name to be MY_FUNCTION
https://api.ipdoctor.net/134.201.250.155
? access_key = YOUR_ACCESS_KEY
& 'callback = MY_FUNCTION'
Example Response: Your API response will be wrapped inside your preferred callback function.
MY_FUNCTION (
{
"ip": "134.201.250.155",
"type": "ipv4",
"continent_code": "NA",
"continent_name": "North America",
"country_code": "US",
"country_name": "United States",
"region_code": "CA",
[...]
}
)
The ipdoctor API supports JSONP Callbacks, enabling you to enter a function name and cause the API to return your requested API result wrapped inside that function. In order to specify a callback
, pass a function name into the API's callback GET parameter.
Errors
Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.
Example Error: The following error is returned if your monthly API request volume has been exceeded.
{
"success": false,
"error": {
"code": 104,
"type": "monthly_limit_reached",
"info": "Your monthly API request volume has been reached. Please upgrade your plan."
}
}
Error Code | Meaning |
---|---|
400 |
Bad Request -- Your request is invalid. |
401 |
Unauthorized -- Your API key is wrong. |
403 |
Forbidden -- The kitten requested is hidden for administrators only. |
404 |
Not Found -- The specified kitten could not be found. |
405 |
Method Not Allowed -- You tried to access a kitten with an invalid method. |
406 |
Not Acceptable -- You requested a format that isn't json. |
410 |
Gone -- The kitten requested has been removed from our servers. |
418 |
I'm a teapot. |
429 |
Too Many Requests -- You're requesting too many kittens! Slow down! |
500 |
Internal Server Error -- We had a problem with our server. Try again later. |
503 |
Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Endpoints
Standard IP Lookup
The Ipdoctor's primary endpoint is called Standard Lookup and is used to look up single IPv4 or IPv6 addresses. To call this endpoint, simply attach any IPv4 or IPv6 address to the API's base URL.
API Request:
https://api.ipdoctor.net/134.201.250.155
? access_key = YOUR_ACCESS_KEY
Parameter | Meaning |
---|---|
IP Address |
[Required] A comma-separated list of IPv4 or IPv6 addresses; you can also enter a domain URLs to have ipdoctor resolve the domains to their underlying IP addresses. (Maxmium allowed values: 50) |
access_key |
[Required] Your API Access Key. |
fields |
[optional] Set to your preferred output field(s) according to the Specify Output Fields section. |
hostname |
[optional] Set to 1 to enable Hostname Lookup. |
security |
[optional] Set to 1 to enable the Security module. |
language |
[optional] Set to a 2-letter language code according to the Specify Output Language section to change output language. |
callback |
[optional] Specify a JSONP callback function name according to the JSONP Callbacks section. |
output |
[optional] Set to json or xml to choose between output formats. |
Response Objects
Response Objects: See the Response Objects section to view detailed descriptions for all API response objects and their values returned by the ipdoctor API.
Depending on your subscription plan and the options you choose for your API request, the ipdoctor API will respond using a series of different modules and objects. Find below a list of all available API response objects explained.
API Response:
{
"ip": "134.201.250.155",
"type": "ipv4",
"continent_code": "NA",
"continent_name": "North America",
"country_code": "US",
"country_name": "United States",
"region_code": "CA",
"region_name": "California",
"city": "Los Angeles",
"zip": "90013",
"location": {
"geoname_id": 5368361,
"capital": "Washington D.C.",
"languages": [
{
"code": "en",
"name": "English",
"native": "English"
}
],
"country_flag_emoji": "🇺🇸",
"calling_code": "1",
"is_eu": false,
"latitude": 34.0453,
"longitude": -118.2413,
},
"time_zone": {
"id": "America/Los_Angeles",
"current_time": "2018-03-29T07:35:08-07:00",
"gmt_offset": -25200,
"code": "PDT",
"is_daylight_saving": true
},
"currency": {
"code": "USD",
"name": "US Dollar",
"plural": "US dollars",
"symbol": "$",
"symbol_native": "$"
},
"connection": {
"asn": 25876,
"isp": "Los Angeles Department of Water & Power"
}
}
Response Object | Description |
---|---|
IP |
Returns the requested IP address. |
hostname |
Returns the hostname the requested IP resolves to, only returned if Hostname Lookup is enabled. |
type |
Returns the IP address type IPv4 or IPv6. |
continent_code |
Returns the 2-letter continent code associated with the IP. |
continent_name |
Returns the name of the continent associated with the IP. |
country_code |
Returns the 2-letter country code associated with the IP. |
country_name |
Returns the name of the country associated with the IP. |
region_code |
Returns the region code of the region associated with the IP (e.g. CA for California). |
region_name |
Returns the name of the region associated with the IP. |
city |
Returns the name of the city associated with the IP. |
zip |
Returns the ZIP code associated with the IP. |
location |
[Object] Returns multiple location-related objects. |
location > geoname_id |
Returns the longitude value associated with the IP. |
location > capital |
Returns the capital city of the country associated with the IP. |
location > languages |
[Object] Returns an object containing one or multiple sub-objects per language spoken in the country associated with the IP. |
location > languages > code |
Returns the 2-letter language code for the given language. |
location > languages > name |
Returns the name (in the API request's main language) of the given language. (e.g. Portuguese ) |
location > languages > native |
Returns the native name of the given language. (e.g. Português ) |
location > country_flag_emoji |
Returns the emoji icon for the flag of the country associated with the IP. |
location > calling_code |
Returns the calling/dial code of the country associated with the IP. (e.g. 351) for Portugal. |
location > is_eu |
Returns true or false depending on whether or not the county associated with the IP is in the European Union. |
location > latitude |
Returns the latitude value associated with the IP. |
location > longitude |
Returns the longitude value associated with the IP. |
time_zone |
[Object] Returns an object containing timezone-related data. |
time_zone > id |
Returns the ID of the time zone associated with the IP. (e.g. America/Los_Angeles for PST) |
time_zone > current_time |
Returns the current date and time in the location associated with the IP. (e.g. 2018-03-29T22:31:27-07:00 ) |
time_zone > gmt_offset |
Returns the GMT offset of the given time zone in seconds. (e.g. -25200 for PST's -7h GMT offset) |
time_zone > code |
Returns the universal code of the given time zone. |
time_zone > is_daylight_saving |
[Returns true or false depending on whether or not the given time zone is considered daylight saving time. |
currency |
[Object] Returns an object containing currency-related data. |
currency > code |
Returns the 3-letter code of the main currency associated with the IP. [USD] |
currency > name |
Returns the name of the given currency. |
currency > plural |
Returns the plural name of the given currency. |
currency > symbol |
Returns the symbol letter of the given currency. |
connection |
[Object] Returns an object containing connection-related data. |
connection > asn |
Returns the Autonomous System Number associated with the IP. |
security |
[Object] Returns an object containing security-related data. |
security > is_proxy |
Returns true or false depending on whether or not the given IP is associated with a proxy. |
security > proxy_type |
Returns the type of proxy the IP is associated with. |
security > is_crawler |
Returns true or false depending on whether or not the given IP is associated with a crawler. |
security > is_tor |
Returns true or false depending on whether or not the given IP is associated with the anonymous Tor system. |
security > blacklist_found |
Returns number of occurrences the ip had been found in blacklist engines. |
security > date |
Returns timestamp of the request. |
check_id |
Returns the check id for futher use in querying. |
Enable Security Data
Example Request:
https://api.ipdoctor.net/103.3.61.114
? access_key = YOUR_ACCESS_KEY
& security = 1
Example Response:
[...]
"security": {
"is_proxy": false,
"proxy_type": null,
"is_crawler": false,
"crawler_name": null,
"crawler_type": null,
"is_tor": true,
"threat_level": "high",
"threat_types": [
"tor"
]
}
[...]
Customers subscribed to the Professional Plus Plan may access the ipdoctor API's Security Data, which can be used to assess risks and threats originating from certain IP addresses before any harm can be done to a website or web application.
In order to use this feature, append the API's security
parameter and set it to 1
.
Example Response: If the Security Data is supported by your subscription plan, the API response will now contain a security
object. For illustration purposes the IP address 103.3.61.114, which is known to be used by the Tor system, has been used for this example API request.
To learn more about each security response object, please refer to the Response Objects section
Sample Code
PHP (cURL)
Standard Lookup: Find below an example for the Standard Lookup Endpoint using PHP cURL.
PHP (cURL)
// set IP address and API access key
$ip = '134.201.250.155';
$access_key = 'YOUR_ACCESS_KEY';
// Initialize CURL:
$ch = curl_init('https://api.ipdoctor.net/'.$ip.'?access_key='.$access_key.'');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Store the data:
$json = curl_exec($ch);
curl_close($ch);
// Decode JSON response:
$api_result = json_decode($json, true);
// Output the "capital" object inside "location"
echo $api_result['location']['capital'];
JavaScript (jQuery.ajax)
Standard Lookup: Find below an example for the Standard Lookup Endpoint using jQuery.ajax.
JavaScript (jQuery.ajax)
// set endpoint and your access key
var ip = '134.201.250.155'
var access_key = 'YOUR_ACCESS_KEY';
// get the API result via jQuery.ajax
$.ajax({
url: 'https://api.ipdoctor.net/' + ip + '?access_key=' + access_key,
dataType: 'jsonp',
success: function(json) {
// output the "capital" object inside "location"
alert(json.location.capital);
}
});
Pricing
Free
This plan features:
- 10.000 requests / mo
- Limited Support
- Location Module
Basic
This plan features:
- 50.000 requests / mo
- Premium Support
- Location Module
- Analytics Support
- SSL Encryption
- Currency Module
- Time Zone Module
- Connection Module
Professional
This plan features:
- 100.000 requests / mo
- Premium Support
- Location Module
- Analytics Support
- SSL Encryption
- Currency Module
- Time Zone Module
- Connection Module
- Bulk Endpoint
Professional Plus
This plan features:
- 100.000 requests / mo
- Premium Support
- Location Module
- Analytics Support
- SSL Encryption
- Currency Module
- Time Zone Module
- Connection Module
- Bulk Endpoint
- Security Module