GlobalCheck API documentation
Important notice
GlobalCheck API is in early beta-testing stage and will change frequently, including breaking changes.
Overview
GlobalCheck is happy to introduce a GlobalCheck Beta API - a modern and powerful tool that allows to automate resources checking and internet monitoring tasks.
GlobalCheck is built the way that is easily lets 3rd-parties to integrate, test and start using it with a few simple requests.
The core capabilities of the service are available trough the GlobalCheck API:
- Getting the list of supported cities
- Getting the list of supported ISPs
- Running various types of tests
- Running single test on specified isp/city
- Running simultaneous test on up to 10 sensors (max.sensors count is a subject to change)
Every API call is a HTTP-request, either GET or POST, signed with authentiation token.
Requests, which requires additional data, are sent as POST-requests with JSON-encoded parameters in their body.
Every API response is returned as JSON payload.
Authentication
In order to perform any API call, you will need to authenticate your requests.
Once you have received your unique authentication token, this will be used to authenticate you when calling the API.
To authenticate your request, your unique authentication token must be passed in additional HTTP header value: X-Globalcheck-Token
Example request:
curl -X GET -H 'X-Globalcheck-Token: your-unique-token' \
'https://api.globalcheck.com/v1/list'
Errors
Normally, all successful API requests ends up with HTTP OK (status code 200) response status and JSON-encoded response body.
In case of handled error, you will see non-200 status code (e.g. 400 (Bad Request) or 401 (Unauthorized)) and json-encoded error description, like:
{"error":"Bad request: wrong tcp port number"}
Retrieving information
To make detailed checks and be able to specify where to perform check, you may need to get additional information about which cities and ISPs are covered by our service.
To acomplish this, GlobalCheck API has several methods:
/v1/list | returns hierarchical list of cities with list of ISPs in each city |
/v1/list/isps | returns hierarchical list of ISPs with list of cities in each ISP |
/v1/list/all-cities | returns plain array of supported cities |
/v1/list/all-isps | returns plain array of supported ISPs |
curl -X GET -H 'X-GlobalCheck-Token: your-personal-token' \
https://api.globalcheck.net/v1/list
{
"RU": {
"Cheboksary": [
"Net By Net Holding LLC"
],
"Izhevsk": [
"OOO NI"
],
"Kazan’": [
"LLC Skynet"
],
...
curl -X GET -H 'X-GlobalCheck-Token: your-personal-token' \
https://api.globalcheck.net/v1/list/isp
{
"Cronyx Plus Ltd.": [
"Moscow"
],
"E-Light-Telecom Ltd.": [
"Kemerovo"
],
...
curl -X GET -H 'X-GlobalCheck-Token: your-personal-token' \
https://api.globalcheck.net/v1/list/all-isps
[
"LANTA Ltd",
"OOO NI",
"VimpelCom",
"Yota",
...
curl -X GET -H 'X-GlobalCheck-Token: your-personal-token' \
https://api.globalcheck.net/v1/list/all-cities
[
"Kazan’",
"Tver",
"Murmansk",
"Lyubertsy",
...
Running tasks
Basically, every new task request is an authorized POST-request with additional JSON-encoded payload in request body.
There are either mandatory and optional parameters in request.
Required parameters:type | string | check type. Currently allowed: "ping", "httpget", "tcpcheck" |
target | string | host/url to check. Could be IP address/hostname for tcpcheck and ping, or valid URL for httpget. |
port | integer | 1-65535, port to check, if type is tcpcheck |
country | string | country code to filter. Currently only 'ru' is supported. |
city | string | city to filter. Can be listed in /v1/list, etc. |
isp | string | ISP to filter. Can be listed in /v1/list, etc. |
Tasks may be executed in two ways: single task on single sensor, or same task on multiple sensors at the same time.
Single checkTo run task on single sensor, form request with the parameters above and call endpoint /v1/run, like these:
Ping targetTarget must be valid hostname or domain name.
curl -X POST -H 'X-Globalcheck-Token: your-unique-token' \
--data '{"type":"ping","target":"google.com","country":"ru"}' \
https://api.globalcheck.net/v1/run
Perform HTTP GET request on targetTarget must be valid URL. NOTE: any url will be truncated to site root. E.g. https://google.com/search will be truncated to https://google.com/
curl -X POST -H 'X-Globalcheck-Token: your-unique-token' \
--data '{"type":"httpget","target":"https://yahoo.com","country":"ru","city":"Moscow"}' \
https://api.globalcheck.net/v1/run
Check specified TCP Port on target
curl -X POST -H 'X-Globalcheck-Token: your-unique-token' \
--data '{"type":"tcpcheck","target":"facebook.com","port":443,"country":"ru","isp":"Rostelecom"}' \
https://api.globalcheck.net/v1/run
Multi-check
To run the same task on multiple sensors at the same time, just call another endpoint: /v1/multirun with same parameters.
In this mode check will be performed on up to 10 sensors at the same time, so that you can compare results, calculate averages and medians, etc.
Actual checks count is limited to 10 (subject to change), but can be reduced by reduced: if we have only 2 sensors in the city given in filter, we can run only 2 checks.
Limitations
For now, default API usage limits are:
10 requests per minute
3 requests per second
These values will most likely be changed many times in the future.