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.

http://proxycheck.io/v1/37.60.48.2&key=111111-222222-333333-444444&vpn=1&asn=1&node=1&time=1&tag=forum signup page

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"
}
 
 

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


Back
Last updated: 29th of June 2017.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: