Iframely API endpoint

Iframely endpoint provides detailed JSON. Basic flow is the same as with oEmbed API:

  • You send your URL via a GET request and receive HTML embed code as html field of JSON response.
  • The HTML embed codes will be responsive whenever possible.
  • Depending on your API settings and/or request parameters, the HTML codes may point to providers domain or be routed via Iframely iFrames.

In addition to primary HTML field, Iframely will also give you URL's semantics and attribution as meta data and all available media options as links. Together, these sections mimic the <head> portion of requested web page and follows Iframely embeds protocol.

API Request

>> http://iframe.ly/api/iframely?url=… &api_key= ….

  • 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.

If you make API calls via JavaScript, and your site uses SSL, change endpoint's protocol to https://.

API Response

>> Here’s sample Iframely API 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 request it
    "html": "<div ... </div>"

    // 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 embed src links with functional rels . For example,
    "links": {
        "player": [{        // List of player embed widgets
            "media": {      // Media query, e.g. aspects
                "aspect-ratio": 1.777778
            },

            // 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", 

            // 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
            },                      // We repeat the same rel
            "rel": ["thumbnail"],   // as iframely.js needs it.
            "type": "image",        // "use href as src of image"
            "href": "http://cdn1.aka ... med_1381670134_00040.jpg"
        }, {
            ...
        }],

                                    // Also possible:
                                    // app, image (as rel)
        ...                         // reader, survey
                                    // logo (rare)
        "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 in unified naming format.

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

Read next: