ForHosting KIT · SEO

Validate hreflang

Hreflang is the one SEO tag that fails almost silently and almost always in pairs: get one direction right and the reciprocal wrong, and search engines can ignore the whole cluster. This endpoint checks every declared alternate against the page it points to and confirms the return link actually exists.

● StableFree · in your browser

Run — free How it works & API

Use it from WebAPIEmailApp soonTelegram soon

Why hreflang breaks so often

Hreflang annotations require every language or region version of a page to list every other version, including itself, and every one of those links has to be reciprocated exactly — if the Spanish page lists English as an alternate, the English page must list Spanish back. Miss one direction and you don't get a partial result; search engines documented early on that they treat an unreciprocated hreflang pair as unreliable and tend to disregard it, which quietly undoes the entire point of adding the tags.

What the validator checks

For a submitted page or cluster, the task collects every hreflang alternate declared, follows each link, and confirms the target page lists a return annotation pointing back. It also validates the language-region codes themselves against the ISO 639-1 and ISO 3166-1 standards the specification requires, catches the common x-default omission on pages meant to serve as a fallback, and flags a self-referencing hreflang that's missing, which search engines expect on every page in the cluster.

A tag with a specific, narrow job

Hreflang was introduced in 2011 to solve one problem: telling a search engine which version of near-duplicate content to serve a given language and region, without that engine mistaking the versions for plain duplicate content. It doesn't influence rankings or translate anything by itself — it's purely a routing signal, which is exactly why a broken reciprocal link is so damaging: the signal simply stops being trusted.

Where it usually breaks in practice

The most common failures come from partial rollouts, where a new region launches with hreflang added only on the new pages and never backfilled onto the existing ones, and from CMS templates that hardcode a language list that quietly goes stale the moment a market is added or retired. Sites that mix hreflang in the HTML head with a separate declaration in the sitemap are also prone to the two falling out of sync, since most teams only ever check one of the two sources.

Running it continuously

Because international sites tend to have the most pages and the most churn, this is one of the highest-value checks to automate: submit the cluster, get a task_id back immediately, and receive the full reciprocity report on your webhook once the crawl finishes. At $0.002 per request, validating an entire language cluster after every content push costs a fraction of the ranking loss one broken pair can cause.

What you can do with it

New market launch check

Confirm every hreflang alternate is reciprocated the moment a new regional site section goes live, before it has a chance to be ignored by search engines.

Sitemap vs. HTML reconciliation

Catch cases where hreflang declared in the sitemap disagrees with what's in the page head, a common source of silent inconsistency.

x-default audit

Verify that pages meant to serve as the fallback for unmatched locales correctly declare x-default rather than defaulting to a specific language by accident.

Post-CMS-migration validation

After switching platforms, confirm the new templates still generate a fully reciprocal hreflang cluster across every language and region.

FAQ

What does the hreflang validator API check?

It confirms every declared hreflang alternate is reciprocated on the target page, validates the language-region codes against ISO standards, and flags missing self-references or x-default tags.

Why does hreflang need to be reciprocal?

Search engines generally disregard an hreflang pair if only one page in the pair declares it, so a missing return link can invalidate the whole cluster, not just one page.

Can it check a whole language cluster in one request?

Yes, submit the set of URLs that make up a cluster and the task returns a per-pair reciprocity report.

Does it validate the hreflang codes themselves?

Yes, codes are checked against ISO 639-1 language and ISO 3166-1 region standards, catching typos and invalid combinations.

Is there a free tier for this endpoint?

The tool above runs free in your browser. The API is paid — each call draws from your prepaid ForHosting KIT balance: top up from $10.00 (it never expires), pay each request's published price, and a call with no balance returns HTTP 402. No subscription, no tokens, and a failed task is never charged.

How much does each check cost?

$0.002 per request, and a failed crawl is retried up to three times before returning an error at no charge.

How do I receive the results?

By signed webhook for automated pipelines, or a signed link valid for 24 hours if you'd rather retrieve it manually.

Does it check hreflang declared in a sitemap as well as in HTML?

Yes, both sources can be submitted, which is how the checker catches cases where the two have drifted out of sync.

For developers — API access

Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.

API endpoint

POSThttps://api.kit.forhosting.com/seo/hreflang-check

Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, and soon from our app, email and Telegram.

Call it from your stack

curl -X POST https://api.kit.forhosting.com/seo/hreflang-check \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d &#39;{"url":"https://ejemplo.com"}'

const res = await fetch("https://api.kit.forhosting.com/seo/hreflang-check", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://ejemplo.com"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/seo/hreflang-check",
    headers={"Authorization": f"Bearer {os.environ[&#39;KIT_KEY']}"},
    json={
    "url": "https://ejemplo.com"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/seo/hreflang-check", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => &#39;{"url":"https://ejemplo.com"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"url":"https://ejemplo.com"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/seo/hreflang-check", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Example request

{
  "url": "https://ejemplo.com"
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "seo.hreflang_check",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.

Pricing

Per request$0.002

Published price — no tokens, no invented credits. A failed task is never charged.

Errors

HTTP	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`402`	`insufficient_balance`	Your balance doesn't cover the task price.
`404`	`unknown_type`	That task type doesn't exist.
`429`	`rate_limited`	Too many requests. Use the webhook instead of polling.

Read the full KIT documentation →

Run — free