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.

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 reqiured.
  • 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: , contact: [email protected].
  • The provided key does not support this endpoint: , 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

Language
Credentials
Query