1. Docs
  2. API endpoints
  3. Iframely API

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": "https://player.vimeo.com/video/141567420",

  // 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 image is returned mostly for pages with a news article. Use it if you need better attribution.

Information rels

Information rels are used mostly to detail what sort of player is being used.

video, audio, playlist

Represents a general video, auidio or playlist players.

slideshow

Slideshow presentation documents, such as Slideshare and similar.

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 is visible. See Autoplay.

attach

Indicates the attachment media. For use with media cards

3d

Virtual and 3D realities.

Feature-policy

The list of rel may also include the number of feature-policy directives that need to be passed into allow attribute of an iFrame for content to properly work.

Iframely recognizes the following feature-policies:

accelerometer, ambient-light-sensor, autoplay, battery, camera, clipboard-write, display-capture, document-domain, encrypted-media, execution-while-not-rendered, execution-while-out-of-viewport, fullscreen, geolocation, gyroscope, legacy-image-formats, magnetometer, microphone, midi, oversized-images, payment, picture-in-picture, publickey-credentials-get, screen-wake-lock, speaker, sync-xhr, usb, vr, vr / xr, wake-lock, web-share, xr-spatial-tracking.

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

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/vnd.apple.mpegurl, application/x-mpegURL

Streaming HTMl5 video.

audio/mp3, audio/mpeg, audio/mp4

HTML5 audio. Will be rendered with as audio.

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:

Docs