Name: Link Preview API: Open Graph, Twitter Card and Favicon
Brand: leadharbor
SKU: api-leadharbor-url-meta
Availability: InStock
Author: API Market

Mohammed Samaan

# URL Meta API

## Overview

The URL Meta API reads a public web page and returns the metadata a link preview needs, as one JSON object. It has 1 endpoint: you pass a URL and get back the page title, description, site name, language, canonical URL, Open Graph image and type, author, published time, theme colour, robots meta, the Twitter Card fields, every icon with its size and `rel`, RSS or Atom feeds, the JSON-LD types found on the page and the first H1. The API follows redirects and reports both the URL you sent and the `final_url` it landed on, and every URL in the response is made absolute against that final URL, so you can use the image and icon links as they are.

It is built for developers adding link previews or unfurls to chat apps, social tools, CMS editors and bookmarking products, SEO and content teams auditing titles, descriptions and Open Graph tags across many pages, and data teams enriching lists of URLs with a title, image and favicon. The response is flat and predictable: plain strings for the main fields, a `twitter` object, an `icons` array, `feeds` and `json_ld_types` arrays, and `null` for any tag the page does not set. The API reads the server-rendered HTML only and does not run JavaScript, and it refuses private and internal addresses.

## Features

*   **1 endpoint**: `GET /v1/market/url-meta` returns all metadata for a page in one call.
*   **Simple input**: A single `url` query parameter with any public `http` or `https` address.
*   **Open Graph and Twitter Card**: Title, description, site name, image and type from Open Graph, and card, site, title, description and image from the Twitter Card tags.
*   **Icons with sizes**: Every favicon and app icon the page declares, with its `sizes` and `rel` values.
*   **Feeds and structured data**: RSS or Atom feed links and the JSON-LD `@type` values on the page, for example `VideoObject`.
*   **Absolute URLs**: Image, icon, canonical and feed URLs are resolved against the final URL after redirects.
*   **Data source and method**: The API fetches the page live and parses its server-rendered HTML. No JavaScript is executed.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Link previews and unfurls**: Show a title, description, image and favicon card when a user pastes a link into a chat, comment box or editor.
*   **SEO audits**: Check that pages set a title, description, canonical URL, Open Graph image and robots meta, and spot missing tags.
*   **Social sharing checks**: Confirm what Facebook, LinkedIn or X will show for a page by reading its Open Graph and Twitter Card values.
*   **Bookmarking and read-later apps**: Save a page with its title, site name, image and favicon.
*   **Feed discovery**: Find the RSS or Atom feeds a site publishes from its home page.
*   **URL list enrichment**: Add a title, language and favicon to a spreadsheet or database of URLs.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/leadharbor/url-meta
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Get URL metadata

Fetches a public page and returns its title, description, Open Graph and Twitter Card data, icons, canonical URL, language, feeds, JSON-LD types and first H1. `status` and `content_type` describe the page response the API received. Tags the page does not set come back as `null`, and lists with nothing in them come back as `[]`. The `meta` object is response metadata (`user` is `null`) that you can ignore.

**Method:** `GET`

**Endpoint:** `/v1/market/url-meta`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | The public page to read, URL-encoded, for example `https%3A%2F%2Fgithub.com`. Private and internal addresses are refused. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/url-meta/v1/market/url-meta?url=https%3A%2F%2Fgithub.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "url": "https://github.com",
  "final_url": "https://github.com/",
  "status": 200,
  "content_type": "text/html",
  "title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub",
  "description": "Join the world's most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.",
  "site_name": "GitHub",
  "language": "en",
  "canonical": "https://github.com/",
  "image": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png",
  "og_type": "object",
  "author": null,
  "published_time": null,
  "theme_color": "#1e2327",
  "robots": null,
  "twitter": {
    "card": "summary_large_image",
    "site": "@github",
    "title": "GitHub · Change is constant. GitHub keeps you ahead. · GitHub",
    "description": "Join the world's most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.",
    "image": "https://images.ctfassets.net/8aevphvgewt8/4pe4eOtUJ0ARpZRE4fNekf/f52b1f9c52f059a33170229883731ed0/GH-Homepage-Universe-img.png"
  },
  "icons": [
    {
      "url": "https://github.githubassets.com/favicons/favicon.png",
      "sizes": null,
      "rel": "alternate icon"
    },
    {
      "url": "https://github.githubassets.com/favicons/favicon.svg",
      "sizes": null,
      "rel": "icon"
    }
  ],
  "feeds": [],
  "json_ld_types": [],
  "h1": "The future of building happens together",
  "meta": {
    "user": null
  }
}
```

**Response fields:**

*   **`url`, `final_url`**: The URL you sent and the URL the API ended on after following redirects.
*   **`status`, `content_type`**: The HTTP status and content type of the page response.
*   **`title`, `description`, `site_name`, `language`, `canonical`**: The core page tags. `description` and `site_name` fall back to `null` when the page does not set them.
*   **`image`, `og_type`, `author`, `published_time`, `theme_color`, `robots`**: Open Graph, article and other meta tags, or `null`.
*   **`twitter`**: The Twitter Card `card`, `site`, `title`, `description` and `image` values.
*   **`icons`**: Each declared icon with its absolute `url`, its `sizes` (for example `32x32`, or `null`) and its `rel`.
*   **`feeds`, `json_ld_types`**: RSS or Atom feed links and JSON-LD types. A YouTube video page, for example, returns `["VideoObject"]` and five icons, four of them with sizes from `32x32` to `144x144`.
*   **`h1`**: The text of the first H1 heading, or `null`.
*   **`meta`**: Response metadata you can ignore.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The page was fetched and its metadata parsed. Missing tags are returned as `null`, not as an error. |
| 400 | Bad Request | The `url` parameter is missing, or it points to a private or internal address. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The request path does not exist. Check that it is `/v1/market/url-meta`. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The target page could not be fetched. Check that the site is up and publicly reachable, then retry. |

## Rate Limits

The Free trial, Starter and PAYG plans each allow 10 requests per second. The Free trial is a 7-day trial with 500 calls, Starter includes 10,000 calls with extra calls billed at $0.001 each, and PAYG charges $0.001 per call with no subscription. Every call counts as one call. Requests above the per-second limit, or after the Free trial calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which says how many seconds to wait. Response time depends on the target site; in our tests the GitHub and YouTube lookups took about 0.9 to 1.0 seconds.

## FAQ

**Does the API run JavaScript on the page?**

No. It reads the server-rendered HTML. Single-page apps that only add their meta tags in the browser can return fewer fields than you see in a browser, while sites that render tags on the server, such as GitHub and YouTube, return the full set.

**Are image and icon URLs ready to use?**

Yes. Every URL in the response is made absolute against `final_url`, so a relative `/favicon.ico` comes back as a full `https://` link.

**What happens with redirects?**

The API follows them. `url` is what you sent and `final_url` is where the page ended up, for example `https://github.com` returns `final_url` `https://github.com/`.

**Why are some fields `null`?**

The page does not set that tag. For example, GitHub's home page has no `author`, `published_time` or `robots` tag, so those are `null`. Empty lists such as `feeds` come back as `[]`.

**Can I read pages on my internal network?**

No. Private and internal addresses are refused with a `400`. The target must be reachable on the public internet.

**What does the `meta` object mean?**

It is response metadata. `user` is always `null` for API.market calls and you can ignore it.

**Which icon should I show in a preview?**

Pick from `icons` by `sizes` when it is set, for example the `32x32` or `48x48` entry, and fall back to the first `icon` entry when every `sizes` value is `null`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Link preview API that returns a page's title, description, Open Graph image, Twitter Card, favicons, canonical URL, feeds and JSON-LD types.

Link Preview API: Open Graph, Twitter Card and Favicon

Free trial