Canonical URL
free/v1/domain/canonicalComprehensive canonical URL audit: extracts canonical tags from HTML and HTTP 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 recommendations.
What It Does
Fetches the page with redirect tracking, parses both HTML <link> tags and HTTP 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.
Why It's Useful
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.
Use Cases
SEO Audit
Verify canonical URLs are correctly set across the site to prevent duplicate content issues.
Catch critical issues like multiple canonicals, body placement, and og:url mismatches that tools like Screaming Frog would flag.
International SEO
Verify hreflang annotations correctly link language/region versions and include x-default.
Ensure correct regional versions appear in local search results with validated language codes.
Site Migration
After migration, verify canonical URLs point to the new domain and redirect chains are clean.
Detect cross-domain canonicals, redirect chains, and HTTP/HTTPS mismatches before they impact rankings.
Continuous Monitoring
Integrate into CI/CD to catch canonical regressions before deployment.
Prevent SEO-breaking changes from reaching production using the score and grade system.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Required | The domain to find canonical URL forExample: example.com |
Response Fields
| Field | Type | Description |
|---|---|---|
domain | string | The queried domain |
requestedUrl | string | The initial URL that was fetched |
finalUrl | string | The URL after following all redirects |
redirectChain | array | URLs in the redirect chain before reaching final content |
canonical | object | Canonical URL details (url, source, httpHeaderUrl, isAbsolute, isHttps, isSelfReferencing, isCrossDomain, canonicalCount, inHead) |
targetValidation | object | Canonical target URL 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 |
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) |
Code Examples
curl "https://api.edgedns.dev/v1/domain/canonical" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d "domain=example.com"const response = await fetch(
'https://api.edgedns.dev/v1/domain/canonical?domain=example.com',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(data);import requests
response = requests.get(
'https://api.edgedns.dev/v1/domain/canonical',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'domain': 'example.com'
}
)
data = response.json()
print(data)Read the full Canonical URL guide
Why it matters, real-world use cases, parameters, response fields, and how to call it from Claude, ChatGPT, or Gemini via MCP.
Read the guide →Related Endpoints
External References
Learn more about the standards and protocols behind this endpoint.
Try This Endpoint
Test the Canonical URL endpoint live in the playground.