--- title: "Iframely API - Embed Codes and Responsive Data" description: "Use embed links to get responsive embed codes for over 1900 domains" --- # Iframely API: media links `links` in [Iframely API](/docs/iframely-api) is the list of objects with fields `rel`, `href`, `type` and `media`. Just like you would expect a `` in `` 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. ## Example of a link object ```json { // 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": "
" } ``` 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](/settings/media). ## 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](https://github.com/atmos/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. ## 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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`, `bluetooth`, `camera`, `clipboard-read`, `clipboard-write`, `display-capture`, `document-domain`, `encrypted-media`, `execution-while-not-rendered`, `execution-while-out-of-viewport`, `fullscreen`, `gamepad`, `geolocation`, `gyroscope`, `hid`, `identity-credentials-get`, `idle-detection`, `local-fonts`, `magnetometer`, `microphone`, `midi`, `otp-credentials`, `payment`, `picture-in-picture`, `publickey-credentials-get`, `screen-wake-lock`, `serial`, `speaker-selection`, `storage-access`, `usb`, `web-share`, `window-management`, `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`, `audio/wav` 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: - ["Responsive embeds"](http://amobil.se/2011/11/responsive-embeds/) by [Anders M. Andersen](https://twitter.com/andmag) / 2011 - [Creating Intrinsic Ratios for Video](http://alistapart.com/article/creating-intrinsic-ratios-for-video) by [Thierry Koblentz](https://twitter.com/thierrykoblentz) / 2009