Getting Started

LinkMetadata Overview

An overview of LinkMetadata and its features.

LinkMetadata provides both an API to retrieve essential metadata from webpages and a component to display links. The source of the metadata is primarily from the Open Graph headers available on the webpage, the home page of the website, and other sources such as security headers, public blocklists, and other sources.

Here is how the component looks like:

How to use the component

First, add the script tag to the page where you want to use the component. If you are using a static site generator, you can add the script tag inside the <head> of your site.

<script type="module" src="https://api.linkmetadata.com/component.js" async></script>

Then, simply add the component HTML tag wherever you want to display the metadata. Multiple instances can be used on the same page and each will be processed individually.

<link-metadata-preview data-url="https://linkmetadata.com"></link-metadata-preview>

Customizing the component

You can customize the component by passing additional attributes to the <link-metadata-preview> tag.

AttributeType / ValuesDefaultWhat it does
data-url requiredstring–The page you want to preview.
data-theme"light", "dark", "card""light"Picks one of the preset colour systems (next section).
data-orientation"horizontal", "vertical""horizontal"Layout: image on the left vs. image on top.
data-show-image"true", "false""true"Show or hide the image.
data-show-branding"true", "false""true"Show or hide the “Preview by LinkMetadata.com” line.
data-original-urlstring—If you pass a canonicalised link to the API but want the card to display the original hostname (useful for campaign links, shortened URLs, etc.).
data-api-endpointstringAPI defaultPoint to your own metadata micro-service. String is prefixed to the encoded data-url.
data-metaJSON string—Skip the fetch entirely and hydrate from pre-rendered metadata (handy for SSR).

All attributes are reactive: change them at runtime and the component re-renders automatically.

Learn more about the customization options in the guide Customizing the Preview Component.

How to use the API

You can use the main endpoint https://api.linkmetadata.com/v1/metadata?url=<URL> using a GET request. For example, in JavaScript and Python:

// Use URLSearchParams to build the query string and ensure it is properly encoded
let params = new URLSearchParams({ url: 'https://linkmetadata.com' });
await fetch(`https://api.linkmetadata.com/v1/metadata?${params.toString()}`);
requests.get(
    "https://api.linkmetadata.com/v1/metadata",
    params={"url": "https://linkmetadata.com"}
)

The API is CORS-enabled, so you can use it from any origin.

You can read more about the API on the Reference Documentation.

LinkMetadata Overview