CleanSnapv1 API
All 25 Developer GuidesMetadata & Parsing
Beginner·5 min read·Topic: extract opengraph metadata node

Extract OpenGraph, Canonical & Article Metadata in Node.js (Zero Dependencies)

Reliably parse `<title>`, OpenGraph tags, Twitter cards, canonical URLs, authors, and publish timestamps without heavy DOM emulators.

Why this breaks in production

Building link previews, bookmark managers, or AI citation cards requires consistent metadata extraction across messy real-world HTML. Sites mix `property='og:image'`, `name='twitter:image'`, single quotes, unquoted attributes, and relative image paths like `/og/cover.png`.

Installing jsdom just to read five `<meta>` tags adds megabytes of overhead and slows serverless cold starts. A clean metadata parser — or a single CleanSnap API call — extracts normalized, resolved fields in milliseconds.

Recommended Engineering Approach

1

Implement fallback chains per field

Check `og:title` → `<title>`, `name='description'` → `og:description` → `twitter:description`, and `og:image` → `twitter:image`.

2

Resolve relative canonical and og:image URLs

Always run `new URL(rawValue, finalUrl)` because many frameworks emit relative OpenGraph paths.

3

Decode HTML entities in titles and descriptions

Convert `&amp;`, `&#39;`, `&mdash;`, and numeric entities so your UI cards never display raw escape sequences.

Working Code Example

extract-metadata-node.tsts
const res = await fetch(
  "https://usecleansnap.com/api/v1/extract?url=" +
    encodeURIComponent("https://nextjs.org/blog") +
    "&includeMetadata=true&includeLinks=false"
);

const { metadata } = await res.json();
console.log({
  title: metadata.title,
  description: metadata.description,
  canonical: metadata.canonical,
  ogImage: metadata.ogImage,
  author: metadata.author,
  publishedTime: metadata.publishedTime,
  language: metadata.language,
});
TRY IT LIVE — ZERO LOGIN

Test this workflow in the CleanSnap Playground

Pre-load the Sample Blog Post or paste your own URL to inspect clean Markdown, token savings, and auto-generated cURL / Node / Python / MCP code.

Run Sample Blog Post

Common Edge Cases & Pitfalls

  • Assuming `<meta>` attributes always appear in `property=... content=...` order misses pages that put `content` before `property`.
  • Using the requested URL instead of the post-redirect `finalUrl` breaks relative image resolution after 301 redirects.
  • Fetching user-supplied URLs directly from your backend without SSRF checks exposes cloud metadata endpoints (`169.254.169.254`).

Frequently Asked Questions

What metadata fields does CleanSnap return?

CleanSnap returns `title`, `description`, `canonical`, `ogImage`, `author`, `publishedTime`, `language`, and `siteName` under the `metadata` object.

Does CleanSnap resolve relative og:image URLs?

Yes, all `ogImage` and `canonical` URLs are resolved against the final post-redirect page URL.

Can I fetch metadata via a simple GET request?

Yes — call `GET /api/v1/extract?url=...&includeMetadata=true` from Node.js, Python, or any edge worker.

Related Developer Guides