API Reference

/1/oembed

get
https://api.embedly.com/1/oembed

oEmbed is Embedly’s basic offering, providing a simple API for embedding content from any URL. This method follows the oEmbed standard.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Response Attributes

type (required)
The resource type. Valid values, along with value-specific parameters are
described below.

version (required)
The oEmbed version number. This must be 1.0.

title (optional)
A text title describing the resource.

author_name (optional)
The name of the author/owner of the resource.

author_url (optional)
A URL for the author/owner of the resource.

provider_name (optional)
The name of the resource provider.

provider_url (optional)
The url of the resource provider.

cache_age (optional)
The suggested cache lifetime for this resource, in seconds. Consumers may
choose to ignore this value.

thumbnail_url (optional)
A URL to a thumbnail image representing the resource. The thumbnail must
respect any maxwidth and maxheight parameters. If this parameter is present,
thumbnail_width and thumbnail_height must also be present.

thumbnail_width (optional)
The width of the optional thumbnail. If this parameter is present,
thumbnail_url and thumbnail_height must also be present.

thumbnail_height (optional)
The height of the optional thumbnail. If this parameter is present,
thumbnail_url and thumbnail_width must also be present.

description
We support and pass back a description for all oEmbed types.

The photo type

This type is used for representing static photos. The following parameters are
defined:

url (required)
The source URL of the image. Consumers should be able to insert this URL
into an <img> element. Only HTTP and HTTPS URLs are valid.

width (required)
The width in pixels of the image specified in the url parameter.

height (required)
The height in pixels of the image specified in the url parameter.

The video type

This type is used for representing playable videos. The following parameters
are defined:

html (required)
The HTML required to embed a video player. The HTML should have no padding
or margins. Consumers may wish to load the HTML in an off-domain iframe to
avoid XSS vulnerabilities.

width
The width in pixels required to display the HTML.

height
The height in pixels required to display the HTML.

The link type

Responses of this type allow a provider to return any generic embed data (such
as title and author_name), without providing either the url or html parameters.
The consumer may then link to the resource, using the URL specified in the
original request.

The rich type

This type is used for rich HTML content that does not fall under one of the
other categories. The following parameters are defined:

html (required)
The HTML required to display the resource. The HTML should have no padding
or margins. Consumers may wish to load the HTML in an off-domain iframe to
avoid XSS vulnerabilities. The markup should be valid XHTML 1.0 Basic.

width
The width in pixels required to display the HTML.

height
The height in pixels required to display the HTML.

Error Codes

JSON or XML Requests

400 Bad Request

  • Required "url" parameter is missing.
  • Either "url" or "urls" parameter is required.
  • Invalid URL format.
  • Invalid "maxheight" parameter.
  • Invalid "maxwidth" parameter.
  • Invalid "urls" parameter, exceeded max count of 20.

401 Unauthorized

  • Invalid key or oauth_consumer_key provided: <key>, contact: [email protected].
  • The provided key does not support this endpoint: <key>, contact: [email protected].
  • URL is private or restricted.

403 Forbidden

404 Not Found
URL Not Found or unable to be accessed by Embedly servers.

Note: Error message will contain Upstream server response.

500 Server issues
Embed.ly is having trouble with this url. Please try again or contact us, [email protected].

501 Not Implemented
Not implemented for format: acceptable values are {json or xml}.

503 Service Unavailable
Note: This happens if our service is down, please contact us immediately: [email protected].

JSONP Requests

Format
callbackFunction({"url": "url with error", "error_code": "error code", "error_message": "error message", "type": "error"})

Error Response
jsonp1273162787542({"url": "http://flickr.com/embedly", "error_code": 404, "error_message": "HTTP 404: Not Found", "type": "error"})

🚧

Want to Try out the oEmbed API?

Try out our handy oEmbed API Explorer. It's awesome and will allow you to preview the response of any URL.

Go to the oEmbed API Explorer

Query Params
string

The URL is to retrieve embedding information. This URL must be escaped to ensure that Embedly retrieves the correct link. For example, this Embedly URL.

string

A comma separated list of urls for Embedly to process. Each URL must be escaped, but commas separating URLS must NOT be URL encoded. urls accepts a maximum of 10 urls at a time. Embedly processes these urls in parallel, therefore, it’s quicker to use urls for batched processing.

int32

This is the maximum width of the embed in pixels. maxwidth is used for scaling down embeds so they fit into a certain width. If the container for an embed is 500px you should pass maxwidth=500 in the query parameters.

int32

This is the maximum height of the embed in pixels. Functions the same as maxwidth, but for the height of the embed instead. It’s noteworthy that maxwidth is preferred over maxheight.

int32

Will scale embeds type rich and video to the exact width that a developer specifies in pixels. Embeds smaller than this width will be scaled up and embeds larger than this width will be scaled down. Note that using this may cause distortion when scaling up embeds.

int32

Will scale embeds type rich and video to the exact height that a developer specifies in pixels. Embeds smaller than this height will be scaled up and embeds larger than this height will be scaled down. Note that using this may cause distortion when scaling up embeds.

string

The response format – Accepted values: (xml, json)

string

Will append the wmode value to the flash object. Possible values include window, opaque and transparent.

string

Returns a (jsonp) response format. The callback is the name of the javascript function to execute.

boolean

By default Embedly does not return script embeds for jsonp requests. They just don’t work and cause lots of issues. In some cases, you may need the script tag for saving and displaying later. In order for Embedly to send the script embeds over jsonp add allowscripts=true. Use with care, and this option is only valid when a callback is supplied, otherwise, it is ignored.

boolean

This will tell the video/rich media to automatically play when the media is loaded. Accepted values: (true, false) Default: false

string
Defaults to 50

The words parameter works by trying to split the description at the closest sentence to that word count

string

chars is much simpler than words. Embedly will blindly truncate a description to the number of characters you specify adding ... at the end when needed.

boolean
Defaults to false

With luxe Embedly’s iframe is initially loaded with poster image and play button rather than loading the whole embed. When the user clicks play the embed is loaded and starts playing.

boolean

secure allows you to serve embeds with a SSL connection. You can also serve images over SSL with our Display product. You can enable this by adding secure=true.

string

scheme allows to set the protocol scheme explicity to http or https. By default embeds are sent back protocol-less so that they will work in any page. You can explicity set a protocol by adding scheme=https.

string

With title Embedly will set the title response attribute to the open_graph, meta, or twitter title if available in the page. Accepted values: (og, twitter, meta)

string

With description Embedly will set the description response attribute to the open_graph, meta, or twitter description if available in the page. Accepted values: (og, twitter, meta)

boolean
Defaults to false

Will return only an image found in meta tags or an API response if set.

boolean
Defaults to false

Turns on/off player analytics

boolean
Defaults to false

Turns on/off Do Not Track support within embed

Responses

Updated about 1 year ago

Language
Credentials
Query
LoadingLoading…
Response
Choose an example:
application/json

Updated about 1 year ago