NAV Navbar
cURL

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.

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:

Basic

This plan features:

Professional

This plan features:

Professional Plus

This plan features:






cURL