LinkMetadata keeps the raw metadata it finds, then builds normalized fields for the common preview use case.

Raw tags vs normalized fields

The og and twitter objects contain raw tag values from the page. They are useful when you need every source field.

The top-level fields are normalized:

• URLs are resolved to absolute URLs.
• Open Graph, Twitter Card, and HTML fallbacks are merged.
• Missing fields use null where possible.
• Image and favicon fields include extra inspection data when available.

Preferred source

The prefer query parameter controls which metadata family is checked first for normalized fields.

const params = new URLSearchParams({
  url: "https://example.com",
  prefer: "twitter"
});

const response = await fetch(`https://api.linkmetadata.com/v1/metadata?${params}`);
const metadata = await response.json();

prefer value	Priority
og	Open Graph, then Twitter Card, then HTML fallbacks.
twitter	Twitter Card, then Open Graph, then HTML fallbacks.

The default is og. Raw og and twitter objects are returned either way.

Titles and descriptions

For title, LinkMetadata checks:

1. Preferred metadata title: og:title or twitter:title.
2. The other metadata title.
3. HTML <title>.

For description, LinkMetadata checks:

1. Preferred metadata description: og:description or twitter:description.
2. The other metadata description.
3. <meta name="description">.

Canonical URL

The normalized url field is selected in this order:

1. Preferred metadata URL: og:url or twitter:url.
2. The other metadata URL.
3. <link rel="canonical">.
4. The originally requested URL.

Relative URLs are resolved against the requested page URL.

Preview image

For Open Graph images, LinkMetadata prefers og:image:secure_url on HTTPS pages, then og:image, then og:image:url.

For Twitter images, it checks twitter:image, then twitter:image:src.

The final image.url follows the prefer setting:

prefer value	Image priority
og	Best Open Graph image, then Twitter image.
twitter	Twitter image, then best Open Graph image.

When an image URL is found, LinkMetadata fetches it to inspect MIME type, dimensions, size, redirect target, and CORS safety. That inspection is best effort, so width, height, type, or size may still be null.

For image CORS behavior, see Images and CORS.

Type

The normalized type field uses the preferred metadata family first:

• og:type when Open Graph wins.
• twitter:card when Twitter Card wins.

If the preferred family is missing, the other family is used as a fallback.

Favicons

LinkMetadata scores favicon candidates and keeps the best one found.

Candidate	Priority
apple-touch-icon or apple-touch-icon-precomposed	Highest
mask-icon, SVG icons, or sizes="any"	High
Generic rel="icon"	Medium
rel="shortcut icon"	Low
/favicon.ico	Fallback

When two candidates have the same priority, the later tag wins.

Non-HTML responses

If the target URL returns non-HTML content, LinkMetadata still returns a normalized response shape. Page text fields are usually null, raw tag maps are empty, and the favicon falls back to /favicon.ico.