Link Preview

API key v1

Title, description, image, favicon and feeds for any public URL.

Fetches a page and returns the metadata a chat app, CMS or newsletter tool needs to show a rich preview: Open Graph and Twitter card tags, the canonical URL, icons, language, author, dates, theme colour, RSS and Atom feeds and the oEmbed endpoint. Results are cached for an hour.

GET https://api.zactonz.com/unfurl/

Parameters

Name	Type	Description
`url`required	string	The page to preview. `https://` is assumed when the scheme is omitted.
`render`	boolean	`1` loads the page in a headless browser before reading its tags. Default
`verify_image`	boolean	`1` downloads the preview image to confirm it exists and to report its real dimensions and type. Default
`fresh`	boolean	`1` bypasses the one-hour cache. Default

Send parameters in the query string.

Response

Field	Type	Description
`status`	integer	`200` on success.
`data`	object	The result.
`data.url`	string	URL as requested.
`data.final_url`	string	URL after redirects.
`data.status`	integer	HTTP status of the page.
`data.title`	string	Best title from Open Graph, Twitter or the title tag.
`data.description`	string	Best description.
`data.site_name`	string	Site name.
`data.type`	string	Open Graph type.
`data.canonical`	string	Canonical URL.
`data.image`	object	Preview image: `url`, `width`, `height`, `alt`, `type`, and with `verify_image` also `verified` and `bytes`.
`data.favicon`	string	Best icon URL.
`data.icons`	array of object	All declared icons with `rel`, `sizes` and `type`.
`data.language`	string	Value of `<html lang>`.
`data.locale`	string	Open Graph locale.
`data.author`	string	Author.
`data.published_time`	string	Publication date as declared.
`data.modified_time`	string	Modification date as declared.
`data.keywords`	array of string	Meta keywords.
`data.theme_color`	string	Theme colour.
`data.twitter`	object	`card`, `site`, `creator`.
`data.feeds`	array of object	RSS, Atom or JSON feeds with `url`, `type`, `title`.
`data.oembed`	string	oEmbed endpoint if declared.
`data.rendered`	boolean	Whether a browser was used.
`data.from_cache`	boolean	Whether the answer came from the cache.

Status codes

The outcome is reported in the JSON status field. See Errors & status codes for the general rules.

`400`	Bad request	`url` is missing, malformed, or points at a host that is not reachable from here.
`413`	Too large	The page is larger than 2 MB.
`415`	Not HTML	The URL does not serve an HTML document.
`422`	Unreachable	The page could not be fetched, or it answered with an error status given in `upstream_status`.
`401`	Unauthorized	The Authorization header is missing or the key is not recognised.
`403`	Forbidden	The key is not licensed for this product.
`429`	Too many requests	The per-minute rate or the plan quota is exhausted. Retry after the seconds given in `Retry-After`.

Notes

Pages are fetched with a normal browser User-Agent and a 2 MB limit. Set render=1 for sites that only populate their tags with JavaScript; a rendered call costs 5 units instead of 1. Hosts that resolve to private or loopback addresses are refused.