API Documentation

IPCHECKAPI offers a user-friendly API interface that empowers users to retrieve a diverse range of information linked to both IPv4 and IPv6 addresses. When a query is made for an IP address, the API furnishes over 40 distinct data points, including geographical details, connectivity statistics, details about the Internet Service Provider (ISP), time zone, currency, and an assessment of security-related information.

This API operates on the REST architecture, where lookup requests can be initiated through simple HTTP GET URLs, and the results are delivered swiftly in a lightweight JSON or XML format, usually within just a few milliseconds.

In this API guide, you will find an exhaustive breakdown of the API's specifications, access methods, and features. Towards the end of the document, you will also discover illustrative code snippets in various programming languages. If you happen to have any lingering technical inquiries, please do not hesitate to reach out to the IPCHECKAPI Customer Support Team.

Specs & Overview

API Access Key & Authentication

After signing up, you will receive an API access key to access any of the API endpoints. To authenticate with the API, you must provide your API access key (YOUR_ACCESS_KEY) in the access_key parameter of the API endpoint URL:

Copyhttps://test1.ipcheckapi.com/api/v1/check?access_key=YOUR_ACCESS_KEY

Keep your API access key safe: Your API access key is private and should at no time be shown publicly. You have the ability to reset it instantly through your account dashboard whenever you deem necessary.

API Response

After a successful API request, the API will provide over 40 distinct response objects containing result data. The API response can be delivered in either JSON or XML format and is organized into four core modules: General information, geographical data, time zone data, currency data, connectivity data, and security data. You will find a comprehensive explanation of the response objects within each module in the API Response Objects section.

Below, you can observe an illustrative API response example for an IPv4 address located in Chicago, United States .

Example API Response:

Please note: In order to provide you with a comprehensive API response, we have included Hostname and Security data in the result presented above. To enable this data for your API response, please follow the guidelines outlined in the following sections of this documentation: Hostname Lookup and Security Data .

API Endpoints

This API offers a total of 3 distinct API endpoints, each serving a unique set of functionalities. Below is a brief summary, and you can click on any of the endpoints to access more detailed information about their usage.

• Standard Lookup

  Look up any given IP address.

• Bulk Lookup

  Look up multiple IP addresses in bulk.

• Origin Lookup

  Look up the IP address the current API request is coming from.

JSONP Callbacks

The API also provides support for JSONP Callbacks , allowing you to integrate the service into your JavaScript applications. To specify the JavaScript function to be invoked, simply include the callback= parameter in your request to any of the API endpoints.

Not sure what JSONP is? Here's an explanation Stack Overflow .

Example API Request:

Copyhttps://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY
    &callback=FUNCTION_NAME

Example API Response:

CALLBACK_FUNCTION({
    {
        "ip": "98.142.250.255",
        "hostname": "98.142.250.255",
        "type": "ipv4",
        "continent_code": "NA",
        "continent_name": "Americas",
        "country_code": "US",
        "country_name": "United States",
        "region_code": "IL",
        [...]
    }
})JSON ONLY              

API Error Codes

In case your API request encounters any issues or fails for any reason, the API will return a JSON error message that provides information about the specific error that occurred. As an illustration, here is an error message that the API will return if the monthly limit of API requests has been exceeded.

Example Error:

Common API Errors:

Endpoints

Standard IP Lookup Available on: All plans

For a single IP address lookup of your preference, you can easily do so by adding the API's ips parameter to your API request URL and specifying a particular IPv4 or IPv6 address. Here's an example API request, the necessary parameters, and a sample API response:

Example API Request:

Copyhttps://test1.ipcheckapi.com/api/v1/info
    ?access_key=YOUR_ACCESS_KEY
    &ips=98.142.250.255

Request Parameters:

Example API Response:

A standard API response will include basic information regarding the provided IP address and its location data. If you are subscribed to the Startup Plan or a higher tier, the API will also provide additional details such as timezone, currency, and connection data.

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.

Bulk IP Lookup Available on: Growth Plan and higher

If you want to perform multiple IP address lookups in a single request, you can do so by adding the API's ips parameter to your API request URL and setting it as a comma-separated list of IPv4 or IPv6 addresses. The API will then respond with an array of results, containing one sub-array per IP address looked up.

Example API Request:

Copyhttps://test1.ipcheckapi.com/api/v1/info
    ?access_key=YOUR_ACCESS_KEY
    &ips=98.142.250.255,103.230.7.255,170.81.55.255

Request Parameters:

Example API Response:

In a Bulk Lookup API response, you will receive an array of results, with each result linked to one of the IP addresses included in the API request. Please note that the API results provided below have been condensed for the sake of readability.

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.

Origin IP Lookup Available on: All plans

If you wish to look up the IP address from which the current API request is originating, simply append check to the API's base URL. The API will then execute a lookup request based on that IP address and furnish a comprehensive set of API results.

Example API Request:

Copyhttps:https://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY

Request Parameters:

Example API Response:

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.

Response Objects

Depending on the subscription plan you have and the specific options you include in your API request, the API has the capability to provide more than 40 distinct response objects. Below, you can find a comprehensive list of API response objects:

Options

Specify Response Format Available on: All plans

The API has the ability to deliver API results in JSON format by default, but you can also specify XML format if needed. You can control the response format by adding the output parameter to your API request URL and setting it to either json or xml.

Example API Request - JSON:

Copyhttps://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY
    &output=json

Example API Request - XML:

Copyhttps://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY
    &output=xml

Would you like to see an API response? Jump to the API Response section.

Specify Response Fields Available on: All plans

API responses from IPCHECKAPI may contain extensive data. To streamline your API result set and focus on specific fields or types of information, you can achieve this by adding the fields parameter to your API request URL and setting it to a single field or a list of fields separated by commas.

Examples:

fields=country_code // returns only the "country_code" object

fields=timezone // returns the complete "timezone" object with sub-objects
fields=timezone.id // returns only the "id" object inside "timezone"

fields=latitude,longitude // returns both the "latitude" and the "longitude" objects

Example API Request - JSON:

Copyhttps://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY
    &fields=latitude,longitude

Would you like to see an API response? Jump to the API Response section.

Enable Hostname Lookup Available on: All plans

To enhance the efficiency of API responses and reduce bandwidth usage, standard IP lookups typically exclude hostname information. If you wish to include hostname data in your API responses, you can easily achieve this by adding the hostname parameter to your API request and setting it to 1.

Example API Request:

Copyhttps://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY
    &hostname=1

Example API Response:

As you can see below, hostname information is now returned right after the IP address.

Please note: Enabling Hostname Lookup can lead to a slight decrease in the speed of API requests.

Enable Security Data Available on: Enterprise Plan

The API can provide important security assessment data, which includes the detection of threats such as the TOR Network and proxies, among others. To incorporate Security Data into your API request, you can do so by adding the security parameter to your API request URL and setting it to 1.

Example API Request:

Copyhttps://test1.ipcheckapi.com/api/v1/check
    ?access_key=YOUR_ACCESS_KEY
    &security=1

Example API Response:

Please note: In the response above, the remaining part of the API response has been omitted for the sake of readability.

Code Examples

PHP (CURL)

Standard Lookup via PHP

Find below a PHP (CURL) example making use of the Standard Lookup endpoint:

// Set IP address and API access key
$ip = '98.142.250.255';
$access_key = 'YOUR_ACCESS_KEY';

// Initialize CURL:
$ch = curl_init('https://test1.ipcheckapi.com/api/v1/info?access_key='.$access_key.'&ips='.$ip.'');
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 "id" object inside "timezone"
echo $api_result['data'][0]['timezone']['id'];

JavaScript (jQuery.ajax)

Standard Lookup via JavaScript (jQuery.ajax)

Find below a JS example making use of the Standard Lookup endpoint:

// Set endpoint and your access key
var ip = '98.142.250.255'
var access_key = 'YOUR_ACCESS_KEY';

// Get the API result via jQuery.ajax
$.ajax({
    url: 'https://test1.ipcheckapi.com/api/v1/info?access_key=' + access_key + '&ips=' + ip,
    dataType: 'jsonp',
    success: function(json) {

        // Output the "id" object inside "timezone"
        alert(json.data[0].timezone.id);

    }
});