Loading IP address geographic location...
Offshore Cloud Services

API

uk ru

Table of contents


Overview

Check request may be performed with an http request:

curl -H "Accept: application/json" \
  'https://check-host.net/check-<CHECKTYPE>?host=<HOSTNAME>&max_nodes=<MAX_NODES>&node=<NODE>'

<CHECKTYPE> is one of the following values: ping, http, tcp, dns, udp
<MAX_NODES> is the maximum number of nodes used for the check
<NODE> is a checking node(s)

Example:

curl -H "Accept: application/json" \
  'https://check-host.net/check-tcp?host=smtp://gmail.com&max_nodes=1'

Response:

{
  "ok":             1,
  "request_id":     "29",
  "permanent_link": "https://check-host.net/check-report/29",
  "nodes": {
    "us1.node.check-host.net": ["us", "USA", "Los Angeles", "5.253.30.82", "AS18978"],
  }
}

request_id is the identifier of the request. Is used for obtaining check results.
permanent_link is a permanent link to the check details.
nodes contains a hash of nodes on which the check is performed. The key is the identifier of the node, and value describes the location of the nodes, IP and ASN.

Check results may be obtained with an http request:

curl -H "Accept: application/json" \
  https://check-host.net/check-result/<REQUEST_ID>

Response:

{
  "us1.node.check-host.net": [[1, 0.131124019622803, "Moved Permanently", "301"]]
}
curl -H "Accept: application/json" \
  https://check-host.net/check-result-extended/<REQUEST_ID>

Response:

{
  "command": "http",
  "created": 1735030010,
  "host":    "http://example.com:80",
  "results": {
    "us1.node.check-host.net": [[1, 0.131124019622803, "Moved Permanently", "301"]]
  }
}

Ping check

curl -H "Accept: application/json" \
  'https://check-host.net/check-ping?host=check-host.net&max_nodes=3'

Response:

{
  "ok":             1,
  "request_id":     "806df9",
  "permanent_link": "https://check-host.net/check-report/806df9",
  "nodes": {
    "us1.node.check-host.net": ["us", "USA", "Los Angeles", "5.253.30.82", "AS18978"],
    "ch1.node.check-host.net": ["ch", "Switzerland", "Zurich", "179.43.148.195", "AS50837"],
    "pt1.node.check-host.net": ["pt", "Portugal", "Viana", "185.83.213.25", "AS44222"]
  }
}

Ping check results

curl -H "Accept: application/json" \
  https://check-host.net/check-result/806df9

Response:

{
  "us1.node.check-host.net": [[
    ["OK", 0.044, "94.242.206.94"],
    ["TIMEOUT", 3.005], 
    ["MALFORMED", 0.045],
    ["OK", 0.0433]
  ]],
  "ch1.node.check-host.net": [[null]],
  "pt1.node.check-host.net": null
}

Node us1.node.check-host.net has performed 4 pings to the host 94.242.206.94. Two successful and two failed: the second one was timed out and the third got a malformed reply.
Node ch1.node.check-host.net was unable to resolve the domain name.
Node pt1.node.check-host.net is still performing the check.


HTTP check

curl -H "Accept: application/json" \
  'https://check-host.net/check-http?host=check-host.net&max_nodes=3'

Response:

{
  "ok":             1,
  "request_id":     "806dfa",
  "permanent_link": "https://check-host.net/check-report/806dfa",
  "nodes": {
    "us1.node.check-host.net": ["us", "USA", "Los Angeles", "5.253.30.82", "AS18978"],
    "ch1.node.check-host.net": ["ch", "Switzerland", "Zurich", "179.43.148.195", "AS50837"],
    "pt1.node.check-host.net": ["pt", "Portugal", "Viana", "185.83.213.25", "AS44222"]
  }
}

HTTP check results

curl -H "Accept: application/json" \
  https://check-host.net/check-result/806dfa

Response:

{
  "us1.node.check-host.net": [[1, 0.13, "OK", "200", "94.242.206.94"]],
  "ch1.node.check-host.net": [[0, 0.17, "Not Found", "404", "94.242.206.94"]],
  "pt1.node.check-host.net": [[0, 0.07, "No such device or address", null, null]]
}

Node us1.node.check-host.net successfully downloaded the page. Downloading the page took about 0.13 seconds. Server 94.242.206.94 responded with 200 status code and message "OK".
Node ch1.node.check-host.net was unable to download page because of a server error — server 94.242.206.94 responded with code 404 and message "Not Found".
Node pt1.node.check-host.net was unable to complete request because of a network error. It was unable to resolve the host name.


TCP connection check

curl -H "Accept: application/json" \
  'https://check-host.net/check-tcp?host=https://check-host.net&max_nodes=3'

Response:

{
  "ok":             1,
  "request_id":     "806dfb",
  "permanent_link": "https://check-host.net/check-report/806dfb",
  "nodes": {
    "us1.node.check-host.net": ["us", "USA", "Los Angeles", "5.253.30.82", "AS18978"],
    "ch1.node.check-host.net": ["ch", "Switzerland", "Zurich", "179.43.148.195", "AS50837"],
    "pt1.node.check-host.net": ["pt", "Portugal", "Viana", "185.83.213.25", "AS44222"]
  }
}

TCP connection check results

curl -H "Accept: application/json" \
  https://check-host.net/check-result/806dfb

Response:

{
  "us1.node.check-host.net": [{"time": 0.03, "address": "104.28.31.42"}],
  "ch1.node.check-host.net": [{"error": "Connection timed out"}],
  "pt1.node.check-host.net": null
}

Node us1.node.check-host.net successfully connected to the host in 0.03 seconds.
Node ch1.node.check-host.net was unable to connect to the host.
Node pt1.node.check-host.net is still performing the check.


DNS address check

curl -H "Accept: application/json" \
  'https://check-host.net/check-dns?host=https://check-host.net&max_nodes=3'

Response:

{
  "ok":             1,
  "request_id":     "806dfc",
  "permanent_link": "https://check-host.net/check-report/806dfc",
  "nodes": {
    "us1.node.check-host.net": ["us", "USA", "Los Angeles", "5.253.30.82", "AS18978"],
    "ch1.node.check-host.net": ["ch", "Switzerland", "Zurich", "179.43.148.195", "AS50837"],
    "pt1.node.check-host.net": ["pt", "Portugal", "Viana", "185.83.213.25", "AS44222"]
  }
}

DNS address check results

curl -H "Accept: application/json" \
  https://check-host.net/check-result/806dfc

Response:

{
  "us1.node.check-host.net": [{
    "A":    ["216.58.209.174"],
    "AAAA": ["2a00:1450:400d:806::200e"],
    "TTL":  299
  }],
  "ch1.node.check-host.net": [{"A": [], "AAAA": [], "TTL": null}],
  "pt1.node.check-host.net": null
}

Node us1.node.check-host.net has found two addresses: one IPv4 and one IPv6.
Node ch1.node.check-host.net was unable to resolve the domain name.
Node pt1.node.check-host.net is still performing the check.


Nodes list

curl -H "Accept: application/json" https://check-host.net/nodes/ips

curl -H "Accept: application/json" https://check-host.net/nodes/hosts

Response:

{
 "nodes": {
   "ru1.node.check-host.net": {
     "asn": "AS14576",
     "ip":  "185.159.82.88",
     "location": [
       "ru",
       "Russia",
       "Moscow"
     ]
   },
   "de1.node.check-host.net": {
     "asn": "AS24940",
     "ip":  "46.4.143.48",
     "location": [
       "de",
       "Germany",
       "Falkenstein"
     ]
   }
 }
}

Using specified nodes for checks

curl -H "Accept: application/json" \
  'https://check-host.net/check-tcp?host=google.com:443&node=us1.node.check-host.net&node=ch1.node.check-host.net'

Response:

{
  "ok":             1,
  "request_id":     "807dab",
  "permanent_link": "https://check-host.net/check-report/807dab",
  "nodes": {
    "us1.node.check-host.net": ["us", "USA", "Los Angeles", "5.253.30.82", "AS18978"],
    "ch1.node.check-host.net": ["ch", "Switzerland", "Zurich", "179.43.148.195", "AS50837"]
  }
}

For Developers

3rd party libraries for API:

tbdsux/check-host - Rust

diasnull/check-host - Python

alirezax5/checkHost - PHP

FlorianMichael/CheckHost4J - Java

Lifailon/Check-Host - PowerShell