# Hreflang Checker + Canonical Checker: Bulk International SEO (`transparent_meteorite/hreflang-canonical-checker`) Actor

Bulk hreflang checker and canonical checker: validates language codes, return tags, x-default, self-reference, canonical target and noindex for every URL or sitemap. No login.

- **URL**: https://apify.com/transparent_meteorite/hreflang-canonical-checker.md
- **Developed by:** [Detroit Web Agent - Open Data](https://apify.com/transparent_meteorite) (community)
- **Categories:** SEO tools, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.17 / 1,000 url checkeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hreflang Checker + Canonical Checker: Bulk International SEO

Hreflang checker and canonical checker for international SEO audits, in bulk. Paste page links or a sitemap and get one row per URL with the canonical, every hreflang entry, and a plain list of what is wrong: invalid language codes, missing return tags, no x-default, no self-reference, canonical pointing somewhere else, broken or redirecting alternates, and noindex pages that make the whole set useless.

It fetches each page over plain HTTP, reads the tags from the HTML head and from the HTTP `Link` header, then opens every alternate page to confirm it links back. No login, no browser, no proxy and no API key.

### Run in 30 seconds

1. Open the **Input** tab. The prefilled list checks 13 well-known multilingual sites.
2. Click **Start**. It finishes in under a minute.
3. Open the **Results** table in the Output tab, or export the dataset as JSON, CSV or Excel.
4. Replace the list with your own URLs, or paste a `sitemap.xml` link, and run again.

### What does this Actor do?

International sites break in quiet ways. A single missing return tag makes Google ignore a language version. A canonical that points to a different page tells search engines your page is a duplicate. A `en_GB` typed with an underscore is silently dropped. This Actor finds those problems on every URL you give it and says exactly what to fix.

For each page it reports:

- **Canonical**: the URL, where it was declared (HTML, HTTP header or both), whether it is self-referencing, absolute, declared once, inside the head, and whether the target returns 200 without redirecting or being noindex.
- **Hreflang set**: every `rel="alternate" hreflang` entry from the HTML, the `Link` header, or the sitemap, with a validity flag and reason for each code.
- **Return tags**: whether each alternate links back to the page (reciprocal annotations, the most common reason hreflang is ignored).
- **x-default and self-reference**: present or missing.
- **Alternate health**: HTTP status of each alternate, redirects, and noindex.
- **Page signals**: HTTP status, redirect hops, noindex from meta robots or `X-Robots-Tag`, `html lang`, title.
- **Issues**: a plain-English list plus an `issueCount` and an `ok` flag, so you can filter a thousand URLs down to the broken ones.

### What is checked

| Check | What it catches |
|---|---|
| Code validity | Underscores (`en_GB`), `UK` instead of `GB`, country code without a language, unknown languages, UN M.49 numbers, bad scripts |
| Return tags | Alternate pages that do not link back (reciprocal hreflang) |
| Self-reference | Page missing from its own hreflang set |
| x-default | No fallback entry |
| Duplicate languages | The same language pointing to two different URLs |
| Alternate status | 404, 5xx, unreachable, redirecting or noindex alternates |
| Canonical | Missing, duplicated, conflicting, relative, outside head, pointing elsewhere, broken target |
| Conflict | Hreflang placed on a page whose canonical points to another URL |
| Page | HTTP errors, redirect chains, noindex, `html lang` that does not match hreflang |

### Limits

- It reads the server HTML. Tags that only appear after JavaScript runs are not seen, which matches what many crawlers see first. Sites that inject hreflang client-side will show as having none.
- Sites that block datacenter traffic (HTTP 403, 429 or 5xx) cannot be read. Those URLs are listed in the run `OUTPUT` and the row is not charged.
- Very large hreflang sets are capped by **Max alternates per page** (default 40). The page itself and x-default are always verified first, and a note is added when entries were skipped.
- Gzipped sitemaps are not unpacked; give the plain `sitemap.xml`.

### Input

| Field | Meaning |
|---|---|
| `urls` | Full page links, one per line. A bare domain like `example.com/page` also works. |
| `sitemapUrl` | Optional `sitemap.xml` or sitemap index. Its pages are added to the list. Hreflang written in the sitemap is used when a page has none in its HTML. |
| `maxUrls` | Upper limit on pages checked (default 100, max 5000). |
| `checkReturnTags` | Fetch each alternate and confirm it links back (default on). |
| `checkCanonicalTarget` | Fetch a canonical that points elsewhere and check it (default on). |
| `maxAlternatesPerPage` | Cap on alternates verified per page (default 40). |

### Example input

```json
{
  "urls": [
    "https://www.example.com/en/",
    "https://www.example.com/de/",
    "https://www.example.com/fr/pricing"
  ],
  "checkReturnTags": true
}
```

Sitemap input:

```json
{ "sitemapUrl": "https://www.example.com/sitemap.xml", "maxUrls": 200 }
```

### Output sample

```json
{
  "url": "https://www.example.com/en/",
  "finalUrl": "https://www.example.com/en/",
  "statusCode": 200,
  "canonical": "https://www.example.com/en/",
  "canonicalSource": "html",
  "canonicalOk": true,
  "hreflangCount": 3,
  "hreflangs": [
    { "lang": "en", "href": "https://www.example.com/en/", "source": "html", "valid": true, "isSelf": true, "status": null, "returnTag": null },
    { "lang": "de", "href": "https://www.example.com/de/", "source": "html", "valid": true, "isSelf": false, "status": 200, "returnTag": false },
    { "lang": "en_GB", "href": "https://www.example.com/gb/", "source": "html", "valid": false, "reason": "uses an underscore, hreflang needs a hyphen (en-GB, not en_GB)" }
  ],
  "hasSelfReference": true,
  "hasXDefault": false,
  "invalidCodes": ["en_GB: uses an underscore, hreflang needs a hyphen (en-GB, not en_GB)"],
  "missingReturnTags": ["https://www.example.com/de/"],
  "noindex": false,
  "issues": [
    "no x-default hreflang",
    "invalid hreflang code en_GB: uses an underscore, hreflang needs a hyphen (en-GB, not en_GB)",
    "missing return tag: https://www.example.com/de/ does not link back to this page"
  ],
  "issueCount": 3,
  "ok": false
}
```

The run also stores an `OUTPUT` record with totals: URLs checked, clean, with issues, unreachable, and any not checked because of the time limit or your cost cap.

### Use cases

- **International SEO audits**: check every market page before a launch or migration.
- **Migrations and relaunches**: confirm hreflang and canonicals survived a URL change.
- **Agencies**: run the same list for each client every month and compare issue counts.
- **Monitoring**: schedule a weekly run on key pages and alert when `ok` turns false.
- **QA before release**: validate language codes and return tags for new locales.
- **Content and localisation teams**: find language versions that exist but are not wired together.

### Pricing

Pay per event, no subscription. Current prices:

| Event | Free | Bronze | Silver | Gold | Platinum | Diamond |
|---|---|---|---|---|---|---|
| Actor Start | $0.00005 | $0.00005 | $0.00005 | $0.00005 | $0.00005 | $0.00005 |
| URL checked | $0.0019 | $0.00177 | $0.001509 | $0.001167 | $0.001167 | $0.001167 |

Tier follows your Apify subscription plan.

Apify's free plan includes monthly platform credit that covers test runs.

Examples at the current price (one `url-checked` event per result; Free-plan tier):

| You pull | You pay |
|---|---|
| 100 results | $0.19 |
| 1,000 results | $1.90 |
| 10,000 results | $19.00 |

Scheduled runs stay cheap when each run only returns new records.

### Integrations and scheduling

Run it on a schedule, then send results to Google Sheets, Slack, email, Make, Zapier or n8n with the Apify integrations, or call it through the REST API and the Python and JavaScript clients. Filter the dataset on `ok = false` to build an alert.

### Use with the API, n8n, Make, Zapier or AI agents

**API** (one call, returns the rows as JSON):

```bash
curl -X POST "https://api.apify.com/v2/acts/transparent_meteorite~hreflang-canonical-checker/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.example.com/en/","https://www.example.com/de/"]}'
```

**Python**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("transparent_meteorite/hreflang-canonical-checker").call(run_input={"urls": ["https://www.example.com/en/"]})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    if not row["ok"]:
        print(row["url"], row["issues"])
```

- **n8n, Make, Zapier:** use the Apify app's "Run Actor" step with actor `transparent_meteorite/hreflang-canonical-checker`, paste the input JSON, then map the dataset items to your sheet.
- **AI agents (MCP):** connect the Apify MCP server at `https://mcp.apify.com?tools=transparent_meteorite/hreflang-canonical-checker` to Claude, Cursor or any MCP client, and your agent can audit hreflang as a tool.

### Fair use and legal

The Actor requests public web pages the same way a search engine crawler does, with a normal user agent and low concurrency. Only check sites you are allowed to audit and respect each site's terms and robots rules. This is an independent tool and is not affiliated with Google or any website it checks.

### FAQ

**Do I need an API key or a login?** No.

**What does "missing return tag" mean?** Page A lists page B as an alternate, but page B does not list page A. Google needs both directions, otherwise it ignores the annotation. The Actor fetches every alternate to test this.

**Which hreflang formats are read?** HTML `link` tags, the HTTP `Link` header, and `xhtml:link` entries in a sitemap you provide. Sitemap entries are used only when the page has none of its own.

**Does it check x-default?** Yes. It reports when x-default is missing. It does not force you to have one, since some sites choose not to.

**Why is my URL listed as not charged?** The site answered with a block (403 or 429), a server error, or no HTML. The row explains why.

**Why did the URL show a redirect issue?** The URL you gave redirects to another one. The Actor follows it and checks the final page, but flags it because hreflang and sitemaps should list final URLs.

**Can it check thousands of URLs?** Yes. Set **Max URLs** up to 5000, or run several batches. Each run stops cleanly before its time limit and lists unchecked URLs so you can resume.

**Does it run JavaScript?** No. It reads the server HTML, which is what most crawlers see first.

**How do I only see the broken pages?** Filter the dataset on `ok = false`, or sort by `issueCount`.

### Support

Found a site that reads wrongly? Open an issue on the Issues tab with the run URL and the page link.

### Related actors

- [Technical SEO Page Audit](https://apify.com/transparent_meteorite/technical-seo-page-audit) for titles, headings, meta tags and on-page checks on the same URLs.
- [Sitemap Link Inventory](https://apify.com/transparent_meteorite/sitemap-link-inventory) to list every URL in a sitemap before you check it.
- [Website Tech Stack Detector](https://apify.com/transparent_meteorite/website-tech-stack-detector) to see which CMS or platform produces the tags.

### Changelog

- **0.1**: First private build. Canonical and hreflang checks, return-tag verification, sitemap input, Link header support.

# Actor input Schema

## `urls` (type: `array`):

Full page links to check, one per line, for example https://example.com/en/pricing. Each page is fetched once and its hreflang and canonical tags are read from the HTML and the HTTP Link header.

## `sitemapUrl` (type: `string`):

A sitemap.xml or sitemap index link. Its pages are added to the list (up to Max URLs), and hreflang written in the sitemap is read when a page has none in its HTML.

## `maxUrls` (type: `integer`):

Upper limit on pages checked in one run, including pages taken from the sitemap.

## `checkReturnTags` (type: `boolean`):

Fetch every alternate page and confirm it links back (reciprocal hreflang). Turn off to only check status codes of alternates, which is faster.

## `checkCanonicalTarget` (type: `boolean`):

When the canonical points to another URL, fetch it and report if it is broken, redirects or is noindex.

## `maxAlternatesPerPage` (type: `integer`):

Caps how many hreflang alternates are fetched and verified for one page. Large global sites list 40 or more.

## Actor input object example

```json
{
  "urls": [
    "https://www.apple.com/",
    "https://www.ikea.com/",
    "https://www.nike.com/",
    "https://www.spotify.com/",
    "https://www.airbnb.com/",
    "https://www.shopify.com/",
    "https://www.microsoft.com/",
    "https://www.samsung.com/",
    "https://www.zoom.us/",
    "https://www.notion.so/",
    "https://www.dropbox.com/",
    "https://www.mozilla.org/en-US/",
    "https://www.philips.com/"
  ],
  "maxUrls": 100,
  "checkReturnTags": true,
  "checkCanonicalTarget": true,
  "maxAlternatesPerPage": 40
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://www.apple.com/",
        "https://www.ikea.com/",
        "https://www.nike.com/",
        "https://www.spotify.com/",
        "https://www.airbnb.com/",
        "https://www.shopify.com/",
        "https://www.microsoft.com/",
        "https://www.samsung.com/",
        "https://www.zoom.us/",
        "https://www.notion.so/",
        "https://www.dropbox.com/",
        "https://www.mozilla.org/en-US/",
        "https://www.philips.com/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("transparent_meteorite/hreflang-canonical-checker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "urls": [
        "https://www.apple.com/",
        "https://www.ikea.com/",
        "https://www.nike.com/",
        "https://www.spotify.com/",
        "https://www.airbnb.com/",
        "https://www.shopify.com/",
        "https://www.microsoft.com/",
        "https://www.samsung.com/",
        "https://www.zoom.us/",
        "https://www.notion.so/",
        "https://www.dropbox.com/",
        "https://www.mozilla.org/en-US/",
        "https://www.philips.com/",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("transparent_meteorite/hreflang-canonical-checker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://www.apple.com/",
    "https://www.ikea.com/",
    "https://www.nike.com/",
    "https://www.spotify.com/",
    "https://www.airbnb.com/",
    "https://www.shopify.com/",
    "https://www.microsoft.com/",
    "https://www.samsung.com/",
    "https://www.zoom.us/",
    "https://www.notion.so/",
    "https://www.dropbox.com/",
    "https://www.mozilla.org/en-US/",
    "https://www.philips.com/"
  ]
}' |
apify call transparent_meteorite/hreflang-canonical-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,transparent_meteorite/hreflang-canonical-checker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/2bwZEE7nSA5EBJJns/builds/M2kCbyAuzmn10qrjr/openapi.json
