hreflang and Canonical Checker: return links, codes, x-default

Give it a list of pages, a sitemap, or both. For each page it reads the canonical and the hreflang alternates, checks them against the rules Google Search Central publishes, and lists every problem with a plain message, such as en-UK: 'UK' is not an ISO 3166-1 alpha 2 region code (the United Kingdom is GB).

It loads every alternate once and checks that it links back, because Google ignores hreflang links between two pages that do not both point to each other [1].

What it checks

hreflang, read from link elements and from the HTTP Link header:

• Each value is a language code in ISO 639-1, optionally followed by a region in ISO 3166-1 alpha 2 or a script in ISO 15924, such as en, en-US or zh-Hant [1]. x-default is accepted. A value with both a script and a region, such as zh-Hant-TW, is flagged as a warning, since Google documents one or the other [1]. A value joined with _ (pt_BR) or a three letter language code (eng) is an error, with the fix in the message.
• Alternate URLs are fully qualified, with http or https [1].
• The page lists itself [1].
• An x-default alternate is present. Google recommends one as the fallback for visitors whose language matches no version [1]. Its absence is a warning.
• No language code points to two different URLs.
• Every alternate loads, does not redirect, and lists this page in its own hreflang set (return link) [1].
• link elements placed in the body are flagged.

Canonical, read from the head, the body and the HTTP Link header:

• A canonical is present.
• Only one canonical URL is given. Google asks you not to give different canonical URLs for the same page [2].
• It is in the head. Google accepts rel="canonical" only in the head [2].
• It is an absolute URL, as Google recommends [2].
• Its target loads and does not redirect.
• On a page with hreflang, it does not point to a version in another language. Google asks for a canonical in the same language [2].

Errors and warnings are this actor's grading. Google's pages describe the rules, not a severity.

Input

• Pages (optional when you give a sitemap)
• Sitemaps (optional): plain or gzipped XML, sitemap index files followed
• Maximum pages (default 200)
• Fetch alternates and canonical targets (default on). Off checks each page's own tags only.
• Maximum extra fetches (default 1,000): alternates and canonical targets loaded beyond the pages being checked. Each URL is loaded once per run.
• Timeout per request (default 20 seconds)

Output

Dataset: one item per page with url, ok, finalUrl, httpStatus, redirected, hreflangCount, selfHreflang, hasXDefault, hreflang (each with hreflang, href, where, validCode, targetStatus, returnLink), canonical, canonicalCount, canonicalIsSelf, canonicalStatus, issues (each with severity, code and message), issueCodes, errorCount and warningCount.

The key value store holds a SUMMARY record with the pages checked, the pages with errors, and any sitemap that could not be read. A page that cannot be loaded gets ok: false and an error, and the rest of the run carries on. Export as JSON, CSV or Excel, or read it over the API.

hreflang annotations inside XML sitemaps are not checked. The actor reads sitemaps only for their page list.

Pricing

Pay per event: one event per page checked. Alternates and canonical targets loaded for the return link checks are not charged. A page that cannot be loaded is not charged. The run stops when it reaches the maximum charge you set.

Scope and conduct

Only public pages are loaded, with at most five requests at a time. No browser is used, nothing is logged in to, and no personal data is collected.

Support

Questions and problems: the Issues tab on this page. Replies are written by an AI assistant on behalf of the developer and reviewed by the developer.

References

[1] Google Search Central, Localized Versions of your Pages. https://developers.google.com/search/docs/specialty/international/localized-versions

[2] Google Search Central, How to Specify a Canonical with rel="canonical" and Other Methods. https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls