Iframely API: media links

links in Iframely API is the list of objects with fields rel, href, type and media. Just like you would expect a <link> in <head> section of the page's HTML to be.

Links are used as raw data which you can use to select and render a media yourself. html field is included as generated responsive embed code based on media.

{
    // SRC of embed. The main attribute
    // can be omitted for apps, for example Twitter and Facebook.
    "href": "//coub.com/embed/2pc24rpb",

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

    // MIME type. Tells: "embed as iFrame"
    "type": "text/html",

    "media": {    // Media query. Mostly responsive
        "aspect-ratio": 1.777778
    },

    // plus generated or native HTML code:
    "html": "<div ..></div>"
}

At times, Iframely will return html attribute without href. For example, for Twitter and Facebook posts, or elsewhere with very specific HTML codes instead of the iFrames or media files.

Also, Iframely does not generate html field for image/* MIME types.

Below is the list of possible rel values as well as information about media queries. You can disable specific use-case rels in your API settings.

Functional use-case rels

rel object contains an array of functional and technical use cases about the rich media. You may disable any of those rels in your settings, should it not fit your app.

Possible primary functional rels:

player
A widget with media playback. Like video, audio or slideshow players.
image
Sizeable photo or picture, indicating that this is the main content of a web page. For example, Imgur, 500px or Droplr.
app
General embed code for an app. For example, Twitter statuses, Facebook posts, Instagrams, etc. Usually comes with inline `html`, but can be an iFrame. Google Maps, for example.
thumbnail
A preview image, usually smaller size, but not guaranteed. We recommend that you do not hot-link third party images on your site. There's Camo, for example.
reader
Longer-form text or graphical widget intended for reader functionality, e.g. Storify. In chat apps, you may want to show it in a popup dialog.
survey
The widget is a questionnaire, e.g. PollDaddy or Apester
summary
Returned if widget is generated by Iframely as summary card or publisher provide its own articles preview card.
file
Downloadable file. We return this rel for direct links to files, including image files. May come together with `reader` e.g. for Office Files, PDFs - where Iframely links to doc viewers.
icon
Attribution favicon or glyph. Can be large enough homepage icon for mobile devices.
logo
Logo image is returned mostly for pages with a news article. Use it if you need better attribution.

Supplementary information rels:

gifv
That comes with `player` rel indicates auto-looping and muted video
playerjs
Flags that player emits JavaScript playback events
autoplay
Player starts media playback when it loads
promo
Indicates the attachment media. For use with promo cards

Technical aspects rels

Iframely also uses supplementary technical rels as the way to flag platform aspects of the media:

ssl
Indicates that embed media is safe to load via HTTPs.
html5
Player is capable of HTML5 playback and will render on devices without Flash installed (for example, iOS).
inline
For `app` indicates that embed widgets can be dynamically added to the page via JavaScript (e.g. doesn’t use `document.write`). Usually goes along with `html` field instead of `href`.

For example, GitHub Gists are not inline as they rely on synchronous document.write script. Facebook embeds are not "inline" for a different reason: the first widget will embed alright, but all the next ones will fail afterward if more of them are added via JavaScript.

MIME types

type suggests a method to render media link as widget. It's a MIME type, as in expected content-type header of a resource behind href of a link. There are following types:

text/html
Widget needs to be rendered as `iframe` unless it has `html` field already.
video/mp4
HTML5 video. Will be rendered with as `video`.
application/x-shockwave-flash
Flash, we suggest to render with `embed`.
application/javascript
JavaScript widget to source as `script` (rarely used).
image and image/*
Image to render as `img`.

Direct links to other binary files (except JavaScript and Flash) will have the file's original MIME type (e.g. application/pdf). They come with file rel.

Sizes in media query

media section is for media query. Iframely generates query’s attributes as well as puts it into usable JSON.

Iframely outputs the following media query attributes at the moment:

  • aspect-ratio - by far our favourite
  • max-width
  • min-height
  • min-width
  • max-height
  • width
  • height

For example, for image rel, Iframely will output exact sizes as width and height in media object. If there is just the height attribute for text\html - stretch iFrame to 100% width.

About responsive HTML code generation

The responsive HTML code for links will be generated by API on the server and added to link object. The exception is image types: thumbnails, icons and logos (to avoid hot-linking).

If you’d like to generate a responsive embed code yourself based on the raw data, please refer to: