oEmbed API endpoint

One of the (only) two Iframely endpoints implements simple oEmbed protocol:

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

API request

iframe.ly/api/oembed?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/oembed/....

If you use Short IDs, you can repeat the API call at iframe.ly/{ID}.oembed. 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 for embed code, if any. Plus other oEmbed-specific data.

Here’s as example response for Coub:

{
    "url": "http://coub.com/view/2pc24rpb",
    "type": "rich",
    "version": "1.0",
    "title": "PARADISE BEACH",
    "author": "Ilya Trushin",
    "author_url": "http://coub.com/trucoubs",
    "provider_name": "Coub",
    "thumbnail_url": "http://cdn1 ... /med_1381670134_00040.jpg",
    "thumbnail_width": 640,
    "thumbnail_height": 360,
    "html": "<div style=\"left: 0px; width: 100%; height: 0px; position: relative; padding-bottom: 56.243%;\"><iframe src=\"//coub.com/embed/2pc24rpb\" style=\"top: 0px; left: 0px; width: 100%; height: 100%; position: absolute;\"></iframe></div>",
}

photo, video and rich types are supported as oEmbed output.

If Iframely couldn't find or generate any embed codes for a given URL, oEmbed will return link type object and URL data. You may opt to raise an error for such URLs so that they do not apply towards your billing (read more).

Heads up: photo per oEmbed spec gives url as link to the image, no html.

Next article: Iframely API