GlobalCheck

RU

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
Examples: 
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.
Optional filtering parameters, could be combined:
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 check

To run task on single sensor, form request with the parameters above and call endpoint /v1/run, like these:

Ping target
Target 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 target
Target 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.

Contents