Iframely API endpoint

Iframely-formatted endpoint provides detailed JSON with all data Iframely could fetch about URL.

Basic flow is the same as with oEmbed API:

  • You send your URL via a HTTP GET request and receive HTML embed code as html field of JSON response.
  • The html and media you get, if any, depends on your API settings and/or optional request parameters.
  • HTML codes may point to providers domain or be displayed via Iframely async iFrames.
  • If request our iFrame, we'll keep rich media in it up-to-date on our end. If you request a native publisher's codes - you need to take care of caching yourself.

In addition to main html field, Iframely will also give you URL's unified semantics and attribution as meta data and all available publisher's media variants as links.

Together, links and meta sections mimic the <head> of the requested web page and follow Iframely embeds protocol.

API request

iframe.ly/api/iframely?url=...&api_key=...

Try it

  • url and api_key parameters are required.
  • url needs to be URL-encoded.
  • for enhanced security, api_key can be substituted with key parameter, which should be the md5 hash value of your actual API key (read more).
  • also, see other available optional query-string parameters.

If you make API calls for each user via client-side JavaScript, use our CDN at cdn.iframe.ly/api/iframely/....

If you use Short IDs, you can repeat the API call at iframe.ly/{ID}.json. You can even fetch data in batches of up to 100 short IDs, separated by - hyphen.

API response

Iframely responds with a JSON that has top-level html field with our recommendation as embed code, if any. Plus all the other information we have.

Here’s an example response for Coub:

{
    "id": "ACcM3Y",
    // short URL ID, if available
    // plus canonical URL
    "url": "http://coub.com/view/2pc24rpb",

    // rel use cases and html code for primary variant of embed,
    "rel": ["player", "ssl"], // check for `autoplay` if you requested it
    "html": "<div ... </div>", // that's the embed code we recommend

    // meta object with attribution & semantics
    "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"        
    },

    // Plus list of all media that we have for this URL:
    // embed src links with functional rels . For example,
    "links": {
        "player": [{        // List of player embed widgets                
            // SRC of embed.
            "href": "//coub.com/embed/2pc24rpb",

            // functional and technical use cases.
            "rel": ["player", "ssl", "html5"],

            // link’s MIME type, says "embed as iFrame".
            "type": "text/html", 

            "media": {      // Media query, e.g. aspects
                "aspect-ratio": 1.777778
            },                

            // plus generated HTML code for simplicity of use:
            "html": "<div ... </div>"
        }, {
            ... 
            // Might have multiple variations of the same player. 
            // Say, one that 'autoplay's, one as MP4 video, one as https.
        }],
        "thumbnail": [{
            "media": {
                "height": 360,      // Exact sizes here. 
                "width": 640
            },                      
            "rel": ["thumbnail"],   // We repeat the same rel for consistency
            "type": "image",        // "use href as src of an image"
            "href": "http://cdn1.aka ... med_1381670134_00040.jpg"
        }, {
            ...
        }],

                                    // Also possible:
                                    // app, image (as rel)
        ...                         // reader, survey, file           
                                    // logo, icon
        "icon": [{
            ...
        }]
    }}
  • rel is the primary information about the use case of the embeds. Primary rels are player, thumbnail, app, image, reader, survey, summary, icon and logo.

  • meta will contain list of semantic attributes we could get and unify to the common naming.

Array values that only have one element will be wrapped as single object (i.e. no []).

Previous article: oEmbed API
Next article: API parameters