OG-Fetch

Simple, bandwidth-efficient OpenGraph metadata extraction for Node.js

Key Features

• Bandwidth efficient - Stops downloading at </head> tag
• Simple API - Just one function: extractOG()
• Streaming approach - Processes data as it arrives
• Zero dependencies - Pure Node.js implementation
• Focused - Does one thing really well

Installation

npm install og-fetch

Usage

const { extractOG } = require('og-fetch');

// Extract OpenGraph metadata
const metadata = await extractOG('https://github.com');

console.log(metadata);
// {
//   title: 'GitHub: Let's build from here',
//   description: 'GitHub is where over 100 million developers...',
//   image: 'https://github.githubassets.com/images/modules/site/social-cards/github-social.png',
//   type: 'website',
//   siteName: 'GitHub',
//   url: 'https://github.com',
//   performance: {
//     responseTime: 845,
//     bytesDownloaded: 26024,
//     stopped: true,
//     redirects: 0
//   }
// }

Examples

• Basic usage: npm run example or node examples/basic.js
• Batch processing: npm run example:batch or node examples/batch.js

API

extractOG(url, options?)

Extracts OpenGraph metadata from a URL.

Parameters:

• url (string) - The URL to extract metadata from
• options (object) - Optional configuration
  • timeout (number) - Request timeout in ms (default: 10000)
  • maxRedirects (number) - Maximum redirects to follow (default: 5)
  • userAgent (string) - Custom user agent

Returns: Promise resolving to metadata object with:

• OpenGraph properties (title, description, image, type, siteName, ogUrl)
• Performance metrics (responseTime, bytesDownloaded, stopped, redirects)
• Original URL

How It Works

OG-Fetch uses a streaming approach to minimize bandwidth usage:

1. Streams HTML as it arrives from the server
2. Searches for </head> tag in incoming data
3. Terminates early when found, saving bandwidth
4. Parses metadata from the downloaded portion

This approach typically downloads only the HTML head section instead of the full page, providing significant bandwidth savings.

Performance

Based on real-world testing:

| Metric | Full Page | OG-Fetch | Improvement | |--------|-----------|----------|---------| | Bytes Downloaded | ~370KB | ~26KB | 93% less |

License

MIT