api / proxycheck.io


General Information

Our API offers two endpoints HTTPS (TLS) and HTTP (Non-TLS). Both reply with a JSON result. By default we only perform a proxy check but you can supply a VPN flag in your API query to perform both a Proxy and VPN check. There are also other flags you can supply such as our tag flag to tag your queries for later analysis inside your dashboard.

Our service is currently load balanced (transparently to users) by three geographically separated servers meaning all requests are split evenly between our servers. If one server within our cluster goes offline for any reason your traffic will gracefully fall to the other servers in our cluster. Our custom cluster architecture is designed to scale and every part of our infrastructure runs on it without exception.


Types of Proxies we detect

We are able to detect all exit nodes used by The Onion Router (TOR), SOCKS4/5 Proxies, Web Proxies and Compromised Servers. We also operate a machine learning inference engine where we gather evidence about an IP Address and perform tests on it to determine whether it's operating as a proxy server without being told that information by a third party.

We also detect VPN services if you supply the VPN flag in your query. We are still building out our VPN database but in general we detect VPN's by storing a database of known data centres. As home users are unlikely to be situated inside a data centre it is likely a virtual private network is being used.


API Call

Below is an example of a Non-TLS API call with optional API Key, VPN, ASN, Time, Node and Tag flags. The IP we're testing belongs to OVH a European datacenter. It is generally recommended to use the non-TLS endpoint as the negotiation time of TLS will take longer than retrieving an answer from our database. You should only use the TLS endpoint if you really need the added protection.

IP Address
This is the IP Address you're performing a query on, you can supply an IPv4 or IPv6 address here.

You can also supply multiple addresses by seperating them with a comma or you can supply them in POST data with the name ips. We allow 100 IP Addresses to be checked in a single query this way and each individual check will accure against your daily query allowance.

      GET Example: 37.60.48.2,47.70.58.3
      POST Example: ips=37.60.48.2,47.70.58.3

      When supplying multiple IP Addresses to be checked via the POST method you can leave the IP Address field in the URL blank.
API Key
This is where you provide your API key, it's not required but without it you'll be limited to 100 free queries per day based on your querying IP Address. Supplying a valid API key (they're free!) increases this limit to 1,000 daily free queries, larger daily query amounts can be purchased from the dashboard.
VPN Check Flag
Please note our VPN detection is very new. A negative detection when performing a VPN check could still mean the IP being checked belongs to a VPN service. We're currently building out our recognition of VPN providers and it is an enormous task for us to detect every single service.
ASN Flag
When using the ASN flag it enables you to view the ASN (Autonomous System Number) of the network for the IP Address you're checking. We also provide the ASN Provider Name and the country of the network if known. Please note using the ASN flag will considerably slow down API answer time by an extra 100ms when queries are usually answered in under 60ms.
Node Flag
When using the Node flag it enables you to view which of our servers answered your query within our cluster for diagnosing specific node issues such as high latency or malformed responses. The node your query is directed to is based on load conditions and so you should only need to supply this flag for diagnostic reasons.
Time Flag
When using the Time flag it enables you to view how long the query you made took to be answered by the node in our cluster. This is mainly for diagnosing issues with specific nodes but you are welcome to use it for informational purposes.
Real-Time Inference Engine Flag
When supplying the inf=0 flag you can deactivate the real-time inference engine which runs on all queries made against the API. When enabled the real-time inference engine will add a 150-300ms increase to query time and so you may wish to turn it off when performing a large query on multiple IP Addresses.
Tag Flag
The tag flag allows you to specify a descriptive term which will be stored with any positive detections by the API and made viewable to you within your dashboard stats tab. In the example we have written "forum signup page" so you would know the positive detections within your stats page came from people accessing your forum signup page.

It is recommended that you send your tag in a POST request instead of a GET request. However we will accept tags in the GET request as shown in the example above. Just be warned that some characters within the tag may be stripped if they're sent in the GET request. Our PHP function on GitHub uses the POST method for sending tags.


API JSON Result Examples

It is recommended that you provision your software to check that the IP returned by the API is the same as the IP you sent with your request and validate the proxy result as either a yes or no declaration. Below are some example responses from the API.

{
    "66.66.66.66": {
        "proxy": "yes",
        "type": "SOCKS"
    }
}
 
{
    "37.60.48.2": {
        "proxy": "yes",
        "type": "VPN",
        "provider": "OVH"
    }
}
{
    "8.8.8.8": {
        "proxy": "no",
        "provider": "GOOGLE"
    }
}
 

Above are three examples of typical API responses for positive proxy detections, positive VPN detections and negative detection results. You should focus only on the ip and proxy yes/no results in your software to determine if the IP tested was a proxy or not as the type and provider responses are for extra information only and you shouldn't rely on those being present to make determinations.

{
    "37.60.48.2": {
        "proxy": "yes",
        "type": "blacklist"
    }
}
{
    "37.60.48.2": {
        "proxy": "yes",
        "type": "whitelist"
    }
}
{
    "error": "Error Text",
    "warning": "Warning Text",
    "service message": "Text"
}
 

{
    "37.60.48.2": {
        "error": "Not processed. Reached 90 second processing time limit."
    }
}

{ "37.60.48.2": { "error": "Not processed. Reached 1,000 IP per query limit." } }
{ "192.168.0.1": { "error": "Invalid or Internal IP Address." } }  

Above are some examples of API responses for the Blacklist and Whitelist feature which is found within your dashboard and also error and warning result examples, we recommend provisioning your software to alert you if you receive error or warning messages as you will receive such messages if you go over your daily query allotment or if your account is disabled.

General Information

Our API offers two endpoints HTTPS (TLS) and HTTP (Non-TLS). Both reply with a JSON result. By default we only perform a proxy check but you can supply a VPN flag in your API query to perform both a Proxy and VPN check. There are also other flags you can supply such as our tag flag to tag your queries for later analysis inside your dashboard.

Our service is currently load balanced (transparently to users) by three geographically separated servers meaning all requests are split evenly between our servers. If one server within our cluster goes offline for any reason your traffic will gracefully fall to the other servers in our cluster. Our custom cluster architecture is designed to scale and every part of our infrastructure runs on it without exception.


Types of Proxies we detect

We are able to detect all exit nodes used by The Onion Router (TOR), SOCKS4/5 Proxies, Web Proxies and Compromised Servers. We also operate a machine learning inference engine where we gather evidence about an IP Address and perform tests on it to determine whether it's operating as a proxy server without being told that information by a third party.

We also detect VPN services if you supply the VPN flag in your query. We are still building out our VPN database but in general we detect VPN's by storing a database of known data centres. As home users are unlikely to be situated inside a data centre it is likely a virtual private network is being used.


API Call

Below is an example of a Non-TLS API call with optional API Key, VPN, ASN, Time, Node and Tag flags. The IP we're testing belongs to OVH a European datacenter. It is generally recommended to use the non-TLS endpoint as the negotiation time of TLS will take longer than retrieving an answer from our database. You should only use the TLS endpoint if you really need the added protection.

IP Address
This is the IP Address you're performing a query on, you can supply an IPv4 or IPv6 address here.
API Key
This is where you provide your API key, it's not required but without it you'll be limited to 100 free queries per day based on your querying IP Address. Supplying a valid API key (they're free!) increases this limit to 1,000 daily free queries, larger daily query amounts can be purchased from the dashboard.
VPN Check Flag
Please note our VPN detection is very new. A negative detection when performing a VPN check could still mean the IP being checked belongs to a VPN service. We're currently building out our recognition of VPN providers and it is an enormous task for us to detect every single service.
ASN Flag
When using the ASN flag it enables you to view the ASN (Autonomous System Number) of the network for the IP Address you're checking. We also provide the ASN Provider Name and the country of the network if known. Please note using the ASN flag will considerably slow down API answer time by an extra 100ms when queries are usually answered in under 60ms.
Node Flag
When using the Node flag it enables you to view which of our servers answered your query within our cluster for diagnosing specific node issues such as high latency or malformed responses. The node your query is directed to is based on load conditions and so you should only need to supply this flag for diagnostic reasons.
Time Flag
When using the Time flag it enables you to view how long the query you made took to be answered by the node in our cluster. This is mainly for diagnosing issues with specific nodes but you are welcome to use it for informational purposes.
Tag Flag
The tag flag allows you to specify a descriptive term which will be stored with any positive detections by the API and made viewable to you within your dashboard stats tab. In the example we have written "forum signup page" so you would know the positive detections within your stats page came from people accessing your forum signup page.

It is recommended that you send your tag in a POST request instead of a GET request. However we will accept tags in the GET request as shown in the example above. Just be warned that some characters within the tag may be stripped if they're sent in the GET request. Our PHP function on GitHub uses the POST method for sending tags.


API JSON Result Examples

It is recommended that you provision your software to check that the IP returned by the API is the same as the IP you sent with your request and validate the proxy result as either a yes or no declaration. Below are some example responses from the API.

{
    "ip": "66.66.66.66",
    "proxy": "yes",
    "type": "SOCKS"
}
 
{
    "ip": "37.60.48.2",
    "proxy": "yes",
    "type": "VPN",
    "provider": "OVH"
}
{
    "ip": "8.8.8.8",
    "proxy": "no"
}
 
 

Above are three examples of typical API responses for positive proxy detections, positive VPN detections and negative detection results. You should focus only on the ip and proxy yes/no results in your software to determine if the IP tested was a proxy or not as the type and provider responses are for extra information only and you shouldn't rely on those being present to make determinations.

{
    "ip": "37.60.48.2",
    "proxy": "yes",
    "type": "blacklist"
}
{
    "ip": "37.60.48.2",
    "proxy": "no",
    "type": "whitelist"
}
{
    "error": "Error Text"
    "warning": "Warning Text"
}
 

Above are some examples of API responses for the Blacklist and Whitelist feature which is found within your dashboard and also error and warning result examples, we recommend provisioning your software to alert you if you receive error or warning messages as you will receive such messages if you go over your daily query allotment or if your account is disabled.

General Information

Within the customer dashboard you will find a few features which also have API's. These include positive detection exporting, account usage exporting and whitelist/blacklist manipulation. Below we'll show you how to interact with these API's so you can fully integrate them into your own software. All queries made against dashboard API's are free and do not incur against your regular API queries made against our proxy/vpn data.


Positive Detection Exporting

Below is the API call url for exporting recent positive detections. Positive meaning these queries yielded positive proxy and VPN detections. By default we limit this to the most recent 100 entries but you can alter the number to view more or less.

API Key
This is where you provide your API key, for all dashboard API queries it's required.
Limiter Flag
By default we show you 100 of your most recent queries however you can change this limit to more or less than 100. You can supply 0 to view all entries, this may take a while depending on how many positive queries you have made and we kindly ask you to not download your entire positive detection history this way frequently and instead use a conservative limit such as the default 100.

"1": {
    "time formatted": "23rd of November 2017 at 7:01 am",
    "time raw": "1511420515",
    "address": "177.154.145.103",
    "detection type": "vpn",
    "answering node": "ATLAS",
    "tag": "Login Attempt"
}

Account Usage Exporting

Below is the API call url for viewing your accounts past 30 days of query volume. It is broken down into Undetected, Proxies, VPN's and Rejected queries.

API Key
This is where you provide your API key, for all dashboard API queries it's required.

"TODAY": {
    "proxies": "18",
    "vpns": "3",
    "undetected": "273",
    "refused queries": "0",
    "total queries": 294
}

Whitelist / Blacklist Manipulation

Below is the API call url for viewing your current whitelist, you can also make additions, removals, set and clear actions to both your White and Blacklists using this API.

Whitelist/Blacklist Select Flag
This is where you choose which list you're going to perform an action on. You can supply either whitelist or blacklist here.
Action Flag
This is where you specify what action you wish to perform. You can choose from the five listed below.

      list - Prints out your current white or black list (depending on which you selected)
      add - Append an entry to the end of your currently selected list
      remove - Remove an entry from your currently selected list
      set - Truncate the list by only saving what you specify in this request
      clear - Clear your entire white or black list (depending on which you selected)
API Key
This is where you provide your API key, for all dashboard API queries it's required.
Post Data
This isn't a URL flag. If you're performing an add, remove or set action you must specify the data you wish to be added, removed or set. To do this you must provide your data in a POST request with the url you've constructed. The name of the post data must be data

Our code does conform to HTML post standards so you can supply \r\n to send a newline enabling you to format your data to make it more readable within your dashboard.

{
    "success": "Added 8.8.8.8 to whitelist."
}

Back
Last update: 5th of Feb 2018.5th of February 2018: New specific error text examples were added to the bottom of the v2 API documentation.

1st of January 2018: Updated the API documentation for our new v2 API endpoint, altered the appearance of the page to use our new CSS style.

23rd of November 2017: New tab interface added to facilitate more API's including our new Dashboard APIs. We added Whitelist and Blacklist API support today.

29th of June 2017: The API JSON Examples were re-made with more response examples added and the text on the page was generally cleaned up.

25th of May 2017: A new tag flag has been added to the API which allows you to tag your queries with a descriptive term for later reference, the example query on this page has been updated to include the new tag flag.

21st of March 2017: The API query example now includes your API key by default if you have one.

1st of January 2017: New API flags were added including the ASN, Node and Time flags.

Advertisement: