Guides

hreflang API

The API runs the same checks as the website and returns JSON. Requests need no key. Each IP address has 60 POST requests per hour, of which five start a check. Status and report reads (GET) are not counted, so polling a job every few seconds is fine. A 429 response carries a Retry-After header. The OpenAPI description lives at /openapi.json.

Check one URL and its cluster

POST /api/v1/check crawls up to 25 URLs and waits up to 90 seconds for the result. A finished check returns 200 with a summary and the report URL. A check still running returns 202 with a status URL to poll.

curl -s https://hreflang.com/api/v1/check \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/en/"}'

Pasted HTML works the same way, with optional response headers and a page URL for resolving relative links:

curl -s https://hreflang.com/api/v1/check \
  -H 'Content-Type: application/json' \
  -d '{"html": "<html><head><link rel=\"alternate\" hreflang=\"en-UK\" href=\"/en/\"></head></html>", "url": "https://example.com/"}'

Larger checks

POST /api/v1/jobs takes url, sitemap or domain and returns 201 with a job ID straight away. Without an email address a job covers up to 100 URLs, with one up to 1000, and the report link arrives by mail.

curl -s https://hreflang.com/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{"sitemap": "https://example.com/sitemap.xml", "email": "seo@example.com"}'

Status, reports and codes

curl -s https://hreflang.com/api/v1/jobs/<job_id>
curl -s https://hreflang.com/api/v1/reports/<hash>
curl -s https://hreflang.com/api/v1/codes/en-UK

Errors come back as {"error": "...", "code": "..."} with a 4xx status.