Hreflang Tag Auditor

Fetches a single public URL, extracts all hreflang alternate-link annotations from its HTML, and validates them for common international SEO mistakes: duplicate language codes, invalid BCP47 tags, a missing x-default fallback, and a missing self-reference. Optionally fetches a limited number of the referenced alternate URLs to check that they link back ("reciprocate") to the original page.

What it does

1. Downloads the HTML of the page given in url.
2. Parses every <link rel="alternate" hreflang="..."> tag and resolves its href to an absolute URL.
3. Checks the extracted set for:
   • a hreflang="x-default" fallback annotation,
   • a self-referencing annotation (the page listing itself),
   • duplicate language codes,
   • hreflang values that are not syntactically valid BCP47 language tags.
4. If checkReciprocity is enabled, fetches up to maxAlternates of the alternate URLs and verifies each one links back to the original page via its own hreflang set.
5. Returns a structured report plus a human-readable list of issues.

Input

Field	Type	Required	Default	Description
url	string	yes	—	Public URL of the page to audit.
checkReciprocity	boolean	no	false	Fetch each alternate URL found to verify it links back to the original page.
maxAlternates	integer	no	10	Maximum number of alternate URLs to fetch when checking reciprocity (capped at 50).

Output

One dataset row per run:

Field	Description
input	The audited URL.
ok	Whether the audit completed successfully.
error	Error message when ok is false (e.g. the URL could not be fetched), null otherwise.
result.url	URL of the audited page.
result.alternates	List of { hreflang, href } pairs extracted from the page.
result.hasXDefault	Whether an x-default annotation is present.
result.selfReferencing	Whether the page references its own URL in its hreflang set.
result.duplicateLangCodes	Language codes that appear more than once.
result.invalidLangCodes	Hreflang values that are not valid BCP47 tags.
result.reciprocityResults	Per-alternate { href, reciprocal, error? }, or null if checkReciprocity was off.
result.issues	Human-readable list of detected problems.

Pricing

Pay per event: $0.005 per page audited. One page's hreflang annotations fetched and fully validated (charged even when no issue is found: the report is complete).

You only pay for these events: the platform usage of the run is covered by the Actor. Failed fetches are not charged. You can cap the cost of a run with the maximum charge setting of your run.

Limits

• Audits one URL per run; only public pages are supported (no login, no paywalled content).
• Fetches time out after 15 seconds.
• maxAlternates is capped at 50 to limit the number of outbound requests per run.
• Reciprocity checking issues a GET request to every selected alternate URL; disable it if you only need the on-page hreflang extraction and validation.
• No personal data is collected or stored.

Use in your workflow

Replace <APIFY_TOKEN> with your token from Apify Console → Settings → API & Integrations.

HTTP API (curl) — run and get the results in one call:

curl -X POST "https://api.apify.com/v2/acts/devoted_laureate_r8f~audit-hreflang/run-sync-get-dataset-items" \
  -H "Authorization: Bearer <APIFY_TOKEN>" -H "Content-Type: application/json" \
  -d '{"url": "https://www.apple.com/", "checkReciprocity": false, "maxAlternates": 10}'

JavaScript (npm install apify-client):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('devoted_laureate_r8f/audit-hreflang').call({"url": "https://www.apple.com/", "checkReciprocity": false, "maxAlternates": 10});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python (pip install apify-client):

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("devoted_laureate_r8f/audit-hreflang").call(run_input={"url": "https://www.apple.com/", "checkReciprocity": False, "maxAlternates": 10})
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

AI agents (MCP) — expose only this Actor as a tool through the Apify MCP server:

{
  "mcpServers": {
    "hreflang-tag-checker": {
      "url": "https://mcp.apify.com?tools=devoted_laureate_r8f/audit-hreflang",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

For agents: call it when you need to validate the hreflang (international SEO) annotations of a web page. Input: url (one page); optional checkReciprocity and maxAlternates. Output: one record with the hreflang entries found and the list of issues (invalid codes, duplicates, missing x-default or self-reference, missing return links). Cost: $0.005 per page audited; failures are not charged.

FAQ

What does a hreflang error look like?

Typical problems are invalid language or region codes (for example en-UK instead of en-GB), the same language listed twice, a missing x-default, or a page that does not reference itself. The report lists each one with the offending value.

What is reciprocity?

Every alternate page should link back to the original. With 'Check reciprocity' on, the Actor fetches up to 'Max alternates' referenced pages and reports which ones do not return the link.

Am I charged if no problem is found?

Yes, one event per page audited: you still get a complete, validated list of the page's hreflang annotations.

Related tools

• Broken Link Checker - Find Dead Links on a Page — alternate URLs that return 404 break hreflang
• Canonical Tag Checker - Bulk Canonical URL Audit — hreflang and canonical tags must point to the same indexable URLs