Canonical URL: a beginner's guide
Find canonical and hreflang URLs
Canonical URLs: how to tell Google which version of a page is the real one
A canonical URL is the official, preferred version of a webpage when multiple URLs return the same (or very similar) content. The mechanism for declaring it is a small line of HTML in the page's `<head>` called the `rel="canonical"` tag, which says, in plain English, "out of all the URLs that show this content, this one right here is the real one — please credit it." It is a hint, not a command — search engines decide whether to honor it — but it is the strongest signal you can give them about which URL deserves the ranking.
You should care because the same content is almost always reachable through more than one URL, even if you have never thought about it. The same product page might be `example.com/products/blue-widget`, `example.com/products/blue-widget?ref=newsletter`, `example.com/products/blue-widget?utm_source=facebook`, and `example.com/products/blue-widget/`. To you, those are all the same page. To Google, they are four different URLs that happen to share the same content — and unless you tell Google otherwise, the ranking signals (backlinks, click-through rate, time on page) get split four ways instead of all credited to one canonical version.
The five things every canonical-URL audit looks at:
Does each public page have a canonical tag? Pages without one force Google to guess which version is the "real" one.
Does the canonical point at the right URL? A common mistake is canonicalizing every page to the homepage, which tells Google to ignore the entire rest of the site.
Does the canonical URL itself return a 200? Pointing your canonical at a URL that 404s is a quiet disaster.
Are HTTP and HTTPS versions both canonicalizing to the HTTPS version? Without this, you can split your ranking signals between the secure and insecure versions of every page.
**Are tracking parameters (`?utm_`, `?ref=`, `?fbclid=*`) canonicalized to the clean URL?** Otherwise every share on social media creates a phantom duplicate.
Three questions a canonical audit answers:
Am I accidentally splitting ranking signals across multiple versions of the same page?
Are any pages canonicalizing to the wrong URL — for example, every product page pointing at the homepage?
Are my marketing tracking parameters quietly creating duplicate-content problems?
The cost of ignoring canonical tags is the slow dilution of every page's ranking power. Each duplicate URL drains a little bit of authority from the version that actually deserves it. The fix is structural: configure your CMS to emit a canonical tag on every public page, pointing at the clean URL. Once it is in place, you can largely forget about it. The canonical-URL standard is documented in Google's own canonicalization guide, and it has not changed in years.
The Canonical URL endpoint, in plain language
In one sentence: Find canonical and hreflang URLs
Comprehensive canonical URL (web address) audit: extracts canonical tags from HTML (HyperText Markup Language) and HTTP (HyperText Transfer Protocol) headers, validates placement, checks for conflicts, analyzes hreflang annotations, detects redirect chains, and cross-references with og:URL. Returns a scored assessment with actionable SEO (Search Engine Optimization) recommendations.
Don't worry if some of the words above are still unfamiliar — there's a plain-language glossary at the bottom of this page, and most of the terms link to their own beginner guides if you want to learn more.
What is actually happening when you call it
Here's what's actually happening behind the scenes when you call this endpoint:
Fetches the page with redirect tracking, parses both HTML (HyperText Markup Language) <link> tags and HTTP (HyperText Transfer Protocol) Link headers for canonical URLs, validates tag placement in <head>, detects multiple/conflicting canonicals, checks og:URL consistency, analyzes hreflang annotations, and grades the overall canonical configuration.
If you're using an AI assistant through MCP, you don't need to understand any of the technical details — the assistant calls the tool and translates the result for you.
Why this specific tool matters
Let's skip the marketing fluff and answer the only question that actually matters: why should you, a real human with a real to-do list, care about the Canonical URL tool? Here's the plain-English version, written the way you'd hear it from a friend who happens to do this for a living.
Canonical URLs tell search engines which version of a page to index. Incorrect canonicals — duplicates, conflicting signals, wrong placement, or cross-domain misconfigurations — can cause indexing failures and lost rankings. This endpoint catches all common canonical issues in a single request.
Picture this in real life. Imagine an SEO specialist. Here's the situation they're walking into: Verify canonical URLs are correctly set across the site to prevent duplicate content issues. Without the right tool, that person would be stuck copy-pasting between five browser tabs, reading documentation written for engineers, and crossing their fingers that the answer they cobble together is correct. With the Canonical URL tool, the same person gets a clear answer in seconds — no spreadsheets, no guessing, no waiting for someone on the infrastructure team to free up.
Three questions this tool answers in plain English. If any of these have ever crossed your mind, the Canonical URL tool is built for you:
Are search engines actually able to crawl, understand, and recommend my pages?
What is the single biggest fix I could make today to climb in Google?
How does my site compare against the technical SEO checklist that the top results all pass?
You can either click the tool and get the answer yourself, or ask your AI assistant — connected through MCP (Model Context Protocol) — to ask the question for you and translate the answer into something you can paste into Slack.
Who gets the most out of this. Marketers, content writers, freelancers running client sites, founders trying to grow without paying for ads, and SEO specialists running monthly health checks. If you see yourself in that list, this is one of the EdgeDNS tools you should bookmark today.
What happens if you skip this entirely. Skip it and search engines quietly stop sending you traffic and you don't find out until the next quarterly review. That's why running this check — even once a month — is one of the cheapest forms of insurance you can give your domain.
Available on the free plan. The technical details: `GET /v1/domain/canonical`.
When would I actually use this?
If you're still on the fence about whether the Canonical URL tool belongs in your toolbox, this section is for you. Below you'll meet three real people — an SEO specialist, a global marketing manager, a SEO engineer, and a devops engineer — facing three real situations where this tool turns a stressful afternoon into a five-minute task. Read whichever story sounds closest to your week.
Story 1: SEO Audit
Imagine you're an SEO specialist. Verify canonical URLs are correctly set across the site to prevent duplicate content issues.
Why it matters: Catch critical issues like multiple canonicals, body placement, and og:URL mismatches that tools like Screaming Frog would flag.
Story 2: International SEO
Imagine you're a global marketing manager. Verify hreflang annotations correctly link language/region versions and include x-default.
Why it matters: Ensure correct regional versions appear in local search results with validated language codes.
Story 3: Site Migration
Imagine you're an SEO engineer. After migration, verify canonical URLs point to the new domain and redirect chains are clean.
Why it matters: Detect cross-domain canonicals, redirect chains, and HTTP/HTTPS mismatches before they impact rankings.
Story 4: Continuous Monitoring
Imagine you're a devops engineer. Integrate into automated deployment workflows to catch canonical regressions before deployment.
Why it matters: Prevent SEO-breaking changes from reaching production using the score and grade system.
Common situations across teams. Beyond the three stories above, here are the everyday workplace moments when people across the company reach for the Canonical URL tool — or one of the tools right next to it in this category. If any of these are on your calendar this month, that's your sign:
Before launching a new page, site, or campaign — to catch the dumb mistakes.
During a quarterly SEO health check.
When organic traffic suddenly drops and you need to find out why.
When pitching a new client and you need an audit deck in under an hour.
If you can see yourself in even one of those bullets, the Canonical URL tool will pay for itself the first time you use it.
Still not sure? Here's the easiest test in the world. Open Claude, ChatGPT, Gemini, or any other AI assistant connected to the EdgeDNS MCP server and ask, in your own words: "Is the Canonical URL tool useful for my job?" The assistant will look at the tool, ask you a couple of follow-up questions about what you're trying to accomplish, and give you a straight answer in plain English. No commitment, no signup forms, no jargon.
The easiest way: just ask your AI assistant
If you've connected the EdgeDNS MCP server to Claude, ChatGPT, Gemini, Cursor, or any other AI assistant, you don't need to write any code. Just ask in plain English:
"Use the Canonical URL tool to check example.com and explain anything that looks wrong in plain language."
The AI will figure out which tool to call, fill in the right parameters, run it, and then explain the result back to you. No copy-pasting between tabs. No reading raw JSON. No memorizing endpoint names.
MCP (Model Context Protocol) access is free on every plan, including the free tier. One API key works for both REST and AI — you do not have to choose.
The technical way: call it from code
If you're a developer and want to call the endpoint from a script or your own application, here's the simplest possible example. Replace the placeholder API key with the real one from your dashboard.
# Replace edns_live_YOUR_KEY with your real API key from the dashboard
curl -H "Authorization: Bearer edns_live_YOUR_KEY" \
"https://api.edgedns.dev/v1/domain/canonical?domain=example.com"What you need to provide
There's just one piece of information you need to provide. The table below explains exactly what it is and what a real value looks like.
| Field | Type | Required? | What it means | Example |
|---|---|---|---|---|
domain | string | Yes | The domain to find canonical URL (web address) for | example.com |
What you get back
When you call this tool, you'll get back a JSON object with the fields below. If you're talking to it through an AI assistant, the assistant reads these for you and explains them in plain language — you don't need to memorize them.
| Field | Type | What you'll see in it |
|---|---|---|
domain | string | The queried domain |
requestedUrl | string | The initial URL (web address) that was fetched |
finalUrl | string | The URL (web address) after following all redirects |
redirectChain | array | URLs in the redirect chain before reaching final content |
canonical | object | Canonical URL (web address) details (URL, source, httpHeaderUrl, isAbsolute, isHttps, isSelfReferencing, isCrossDomain, canonicalCount, inHead) |
targetValidation | object | Canonical target URL (web address) validation (status, isReachable, hasNoindex, isChain, chainTarget, targetRedirected) — null if self-referencing |
ogUrl | string | The og:URL meta tag value for cross-signal comparison |
ogUrlMatch | boolean | Whether og:URL matches the canonical URL (web address) |
hreflang | object | Hreflang analysis (alternates array, count, hasXDefault) |
score | number | Canonical health score from 0-100 |
grade | string | Letter grade (A-F) based on score |
issues | array | Severity-graded issues with codes and recommendations (critical, warning, info) |
Words you might be wondering about
If any words on this page felt like jargon, here's a plain-language version. Click any linked term to read a full beginner-friendly guide.
URL (web address) — The full address of a page, like https://example.com/about.
HTTP (HyperText Transfer Protocol) — The language web browsers and websites use to talk to each other.
HTTPS (secure HyperText Transfer Protocol) — HTTP with encryption — the little padlock in your browser. It means nobody between you and the website can read what you're sending.
SEO (Search Engine Optimization) — Everything you do to help search engines like Google find, understand, and rank your website.
HTML (HyperText Markup Language) — The basic language web pages are written in. The tags you see in the source code (<h1>, <p>, <a>) are HTML.
Need Programmatic Access?
Automate domain intelligence with 100+ API endpoints and a free MCP server for AI integration.