Iframely Self-Hosted API

Iframely is a self-hosted version of the Iframely APIs and HTML parsers. It takes a URL and returns its metadata, including rich media embeds (layers, posts, slideshows, maps, etc.).

Key features include:

• Domain Parsers: Specific parsers for popular publishers like YouTube, Facebook, Instagram, Twitter, SoundCloud, Google Maps, TED, and Twitch.
• Protocol Support: Coverage of many domains via oEmbed, Open Graph, Twitter Cards, and microformats.
• Whitelist Management: By default, it fetches a central whitelist from Iframely, but you can replace it with your own custom whitelist file.
• Node.js Integration: Can be used directly as a Node.js library.

When choosing between the self-hosted version and the Iframely Cloud API, be aware of the following limitations in the self-hosted version:

• No Hosted iFrame Renders: The self-hosted version does not return Iframely.com-powered iFrame renders in the html field. You are responsible for rendering the media using the provided metadata.
• Missing Cloud Features: Features like per-URL customization, predictive sizing for JS-based embeds, lazy-loading, and type-based media whitelists are exclusive to the Cloud API.
• Limited Domain Plugins: The open-source version includes core domain parsers but does not receive new publisher updates as frequently as the Cloud version. However, you can extend the self-hosted version with your own private plugins.

The whitelist uses top-level keys for domain names. It supports wildcard entries (e.g., *.sub.domain.com). When querying a URL like http://name.sub.domain.com/slug, the system follows this priority algorithm:

1. Check for an exact match: name.sub.domain.com
2. Check for a subdomain wildcard: *.sub.domain.com
3. Check for a top-level wildcard: *.domain.com

Note on www: www.domain.com and domain.com are treated as identical in most cases. If www.domain.com is not explicitly listed, check domain.com instead of using *.domain.com to avoid potential errors.

The Iframely whitelist file allows parsers to identify which domains can provide rich media embeds via protocols like Iframely, oEmbed, Twitter Cards, and Open Graph.

By default, the self-hosted Iframely instance fetches updates from http://iframely.com/qa/whitelist.json. You can override this by downloading the file, customizing it, and uploading it to the /whitelist folder of your server.

File Naming Convention: To allow the server to update the whitelist without a restart, include a timestamp in the filename: iframely-YYYY-MM-DD-HH-mm-UTC.json (e.g., iframely-2013-08-27-14-18-UTC.json).

Iframely normalizes various semantic standards (such as oEmbed, Open Graph, Twitter Cards, and Dublin Core) into a unified meta object. This allows you to access consistent naming keys regardless of the source platform's original metadata format. The meta object is returned as part of the API response and contains fields for general information, attribution, statistics, geographic data, and product information.

"meta": {
	"title": "PARADISE BEACH",  
	"description": "Ilya Trushin",
	"author_url": "http://coub.com/trucoubs",
	"author": "Ilya Trushin",
	"site": "Coub",
	"canonical": "http://coub.com/view/2pc24rpb",
	"keywords": "living photo, ... , media"        
}

To retrieve semantics, attribution metadata, and embed links for a specific URL, send an HTTP GET request to the Iframely API endpoint.

Parameters

• url (Required): The URL you want to embed. This must be URL-encoded.
• api_key (Required): Your API key.
• key (Optional): For enhanced security, you can use the MD5 hash of your API key instead of the raw api_key.
• group (Optional): For open-source users, add &group=true to the request to ensure the links array is grouped by rel (matching the Cloud API behavior).

Protocol Choice

• HTTPS: Use https://iframe.ly/api/iframely if your site uses SSL and you are making calls via JavaScript.
• HTTP: Generally faster for server-to-server communications as it avoids additional handshakes.

Iframely uses standard HTTP status codes to indicate the success or failure of a request. A successful request returns HTTP 200. Any processing error with a URL will return an HTTP 4xx error code.

In addition to the HTTP status code, the response body contains a JSON object specifying the error status and message:

{
  "status": "404",
  "error": "Not Found"
}

Note that URLs resulting in an error do not count towards your API usage limits or billing. You can also configure your settings at iframely.com/settings to return an error if no media matches your specific requirements.

To render widgets from the API response, iterate through the links array and use $.iframely.generateLinkElement(link, data) to create the HTML element for each link.

To prevent scrollbars in reader rel iframes (specifically type="text/html" widgets like GitHub Gists), call $.iframely.registerIframesIn(container) after rendering. This allows the library to listen for resize messages from the iframe and adjust its size to fit the content dynamically.

// Iterate through all links.
data.links.forEach(function(link) {

    // Call generator to create html element for a link.
    var $el = $.iframely.generateLinkElement(link, data);

    // Add element to body.
    $('body').append($el);
});

// Call this to handle iframe resizing and prevent scrollbars
$.iframely.registerIframesIn($('body'));

The iframely.js client library facilitates API calls to the /iframely endpoint and renders responsive embed widgets. It requires jQuery as a dependency.

Include both jQuery and iframely.js in your page's <head> section. You should host iframely.js on your own domain (the same domain where your Iframely Gateway is hosted) for production use.