Check-Host API — Installation Guide

FastAPI service that checks host reachability via check-host.net, from any of its worldwide nodes. Supports ping, http, tcp, udp, and dns checks.

Files

api/index.py       FastAPI app — all logic in one file
requirements.txt

1. Run locally

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn api.index:app --reload --port 8000

Visit http://localhost:8000/docs for interactive API docs.

2. Routes

GET /api/{check_type}/{country}/{host}
    check_type: ping | http | tcp | udp | dns
    country:    2-letter code (e.g. "de") or "all" for every node — required, no default
    example:    /api/ping/de/example.com

GET /api/full/{country}/{host}
    Runs all 5 check types in parallel.
    example: /api/full/all/example.com

GET /nodes
    Lists every available country code, pulled live from check-host.net/nodes/hosts.

GET /{country}/{host}
GET /check/{country}/{host}
    Legacy routes, always run a ping check (kept for backward compatibility).

GET /?host=example.com&country=de&type=http
    Same as /api/{type}/{country}/{host}, query-string form.
    country is required here too — omitting it returns HTTP 400.

3. Deploy on Render

1. Push this repo to GitHub.
2. In Render: New + → Web Service → select the repo.
3. Settings:
   • Build Command: pip install -r requirements.txt
   • Start Command: uvicorn api.index:app --host 0.0.0.0 --port $PORT
4. No environment variables are required.
5. Deploy — Render assigns a public URL automatically.

4. Deploy anywhere else (Docker-free, any host with Python)

pip install -r requirements.txt
uvicorn api.index:app --host 0.0.0.0 --port 8000 --workers 2

Put it behind Nginx/Caddy if you need HTTPS and a custom domain.

Compatibility with the Cloudflare-Scamalytics worker

https://github.com/mehdi-hexing/Cloudflare-Scamalytics calls this API's legacy route (GET /{country}/{host}) directly, hardcoded to https://check-host.onrender.com. This repo is kept compatible with it:

• Every ping result includes a ping_ms field (the worker's frontend reads this exact key to show latency per node).
• Every error response includes both detail and message (the worker reads message to surface a real error to the user instead of a generic "HTTP 502").
• CORS is open (Access-Control-Allow-Origin: *) since the API is public and read-only.

If you deploy this API under a different URL than check-host.onrender.com, update CH_RENDER_API_BASE in that worker's _worker.js accordingly.

Notes

• The node list is cached in memory for 6 hours to avoid hitting check-host.net on every request; it refreshes automatically after that.
• country has no default anywhere — every request must specify one explicitly (or pass all).
• This code could not be tested live against check-host.net in the environment it was written in (no network access to that domain), so response parsing is written defensively with a raw fallback field. Test against a few real hosts before production use, especially for tcp/udp/dns.