{"__v":9,"_id":"564de2ddfe07a81700b5c3ab","category":{"__v":12,"_id":"564df3217c8f372b00b934df","pages":["564e01de8980c32b009e8bca","564e031f5eab6e0d0069ca38","564e057a873c362d005172b2","564e05a15eab6e0d0069ca40","564e07b01494cc2b00acb618","56941291d8c04d1700e5adc2","5696aca1cb14e11700f8aa01","56d46a4f73dcd20b00fb8647","56d46a5b8001e30b00896ebb","56f00bd1d58ed32400df6092","56f01568d58ed32400df60c1","56f0194911415c2900969c10"],"project":"564de2dbfe07a81700b5c3a5","version":"564de2dbfe07a81700b5c3a8","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-11-19T16:04:49.459Z","from_sync":false,"order":0,"slug":"api","title":"API"},"editedParams":true,"editedParams2":true,"parentDoc":null,"project":"564de2dbfe07a81700b5c3a5","user":"564de2b4fe07a81700b5c3a4","version":{"__v":8,"_id":"564de2dbfe07a81700b5c3a8","project":"564de2dbfe07a81700b5c3a5","createdAt":"2015-11-19T14:55:23.838Z","releaseDate":"2015-11-19T14:55:23.837Z","categories":["564de2ddfe07a81700b5c3a9","564df317826645210097a890","564df3217c8f372b00b934df","564e5227c3553e0d003e53ba","5666dac5d784a70d00397bcb","56cd08ddd98d851d00c0c3bd","56e9a50946bfd60e008840a7","5718e37bf8f7de1900683fad"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-19T14:55:25.953Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"javascript","code":"// jQuery\n$.getJSON('https://api.embedly.com/1/oembed?' + $.param({\n  url: 'https://www.youtube.com/watch?v=jofNR_WkoCE',\n  key: \":key\"\n}));\n\n// jQuery Embedly \n$.embedly.oembed('https://www.youtube.com/watch?v=jofNR_WkoCE', {key: \":key\"});"},{"language":"curl","code":"curl \"http://api.embedly.com/1/oembed?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DjofNR_WkoCE&key=:key\""},{"language":"python","code":"import requests\n\n# Create the query\nquery = {\n  \"url\": \"https://www.youtube.com/watch?v=jofNR_WkoCE\",\n  \"key\": \":key\"\n}\n\n# Make the call.\nr = requests.get('https://api.embedly.com/1/oembed', params=query)\n\n# print the json result.\nprint r.json()\n"}]},"results":{"codes":[{"name":"","code":"{\n  \"type\": \"video\",\n  \"url\": \"http://www.youtube.com/watch?v=jofNR_WkoCE\",\n  \"provider_name\": \"YouTube\",\n  \"provider_url\": \"https://www.youtube.com/\", \n  \"title\": \"Ylvis - The Fox (What Does The Fox Say?) [Official music video HD]\",\n  \"description\": \"iTunes: http://smarturl.it/YlvisFox Fra I kveld med Y...\", \n  \"author_name\": \"TVNorge\",\n  \"author_url\": \"https://www.youtube.com/user/tvnorge\",\n  \"html\": \"<iframe class=\\\"embedly-embed\\\" src=\\\"//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FjofNR_WkoCE%3Ffeature%3Doembed&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DjofNR_WkoCE&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FjofNR_WkoCE%2Fhqdefault.jpg&key=internal&type=text%2Fhtml&schema=youtube\\\" width=\\\"854\\\" height=\\\"480\\\" scrolling=\\\"no\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\",\n  \"width\": 854,\n  \"height\": 480, \n  \"thumbnail_url\": \"https://i.ytimg.com/vi/jofNR_WkoCE/hqdefault.jpg\", \n  \"thumbnail_width\": 480,\n  \"thumbnail_height\": 360,\n  \"version\": \"1.0\"\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"564de4a9fe07a81700b5c3b2","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"string","name":"url"},{"_id":"564df12e7441dc350097531b","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"string","name":"urls"},{"_id":"564de4a9fe07a81700b5c3b1","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"int","name":"maxwidth"},{"_id":"564df12e7441dc350097531a","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"int","name":"maxheight"},{"_id":"564df2897441dc350097531f","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"int","name":"width"},{"_id":"56c5deb60fba010d004307bb","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"int","name":"height"},{"_id":"564df2897441dc350097531e","ref":"","in":"query","required":false,"desc":"The response format – Accepted values: (xml, json)","default":"","type":"string","name":"format"},{"_id":"564df2897441dc350097531d","ref":"","in":"query","required":false,"desc":"Will append the wmode value to the flash object. Possible values include window, opaque and transparent.","default":"","type":"string","name":"wmode"},{"_id":"564dfad332e48b0d005f9db0","ref":"","in":"query","required":false,"desc":"Returns a (jsonp) response format. The callback is the name of the javascript function to execute.","default":"","type":"string","name":"callback"},{"_id":"564dfad332e48b0d005f9daf","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"boolean","name":"allowscripts"},{"_id":"564dfad332e48b0d005f9dae","ref":"","in":"query","required":false,"desc":"This will tell the video/rich media to automatically play when the media is loaded. Accepted values: (true, false) Default: false","default":"","type":"boolean","name":"autoplay"},{"_id":"564dfad332e48b0d005f9dad","ref":"","in":"query","required":false,"desc":"The words parameter works by trying to split the description at the closest sentence to that word count","default":"50","type":"string","name":"words"},{"_id":"564dfad332e48b0d005f9dac","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"string","name":"chars"},{"_id":"564dfad332e48b0d005f9dab","ref":"","in":"query","required":false,"desc":"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.","default":"0","type":"boolean","name":"luxe"},{"_id":"564dfad332e48b0d005f9daa","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"boolean","name":"secure"},{"_id":"564dfad332e48b0d005f9da9","ref":"","in":"query","required":false,"desc":"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.","default":"","type":"string","name":"scheme"},{"_id":"569fbbfc4583912300b5ef77","ref":"","in":"query","required":false,"desc":"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)","default":"","type":"string","name":"title"},{"_id":"569fbc26b4f2d31900898cf8","ref":"","in":"query","required":false,"desc":"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)","default":"","type":"string","name":"description"},{"_id":"56f2b8e8d67b16190084cd0e","ref":"","in":"query","required":false,"desc":"Will return only an image found in meta tags or an API response if set.","default":"0","type":"boolean","name":"meta_images"}],"url":"/1/oembed"},"isReference":true,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Attributes\"\n}\n[/block]\n\n``type`` (required)\n    The resource type. Valid values, along with value-specific parameters are\n    described below.\n\n``version`` (required)\n    The oEmbed version number. This must be 1.0.\n\n``title`` (optional)\n    A text title describing the resource.\n\n``author_name`` (optional)\n    The name of the author/owner of the resource.\n\n``author_url`` (optional)\n    A URL for the author/owner of the resource.\n\n``provider_name`` (optional)\n    The name of the resource provider.\n\n``provider_url`` (optional)\n    The url of the resource provider.\n\n``cache_age`` (optional)\n    The suggested cache lifetime for this resource, in seconds. Consumers may\n    choose to ignore this value.\n\n``thumbnail_url`` (optional)\n    A URL to a thumbnail image representing the resource. The thumbnail must\n    respect any maxwidth and maxheight parameters. If this parameter is present,\n    thumbnail_width and thumbnail_height must also be present.\n\n``thumbnail_width`` (optional)\n    The width of the optional thumbnail. If this parameter is present,\n    thumbnail_url and thumbnail_height must also be present.\n\n``thumbnail_height`` (optional)\n    The height of the optional thumbnail. If this parameter is present,\n    thumbnail_url and thumbnail_width must also be present.\n\n``description``\n    We support and pass back a description for all oEmbed types.\n\n\n###The photo type\n\nThis type is used for representing static photos. The following parameters are\ndefined:\n\n``url`` (required)\n    The source URL of the image. Consumers should be able to insert this URL\n    into an``<img>``element. Only HTTP and HTTPS URLs are valid.\n\n``width`` (required)\n    The width in pixels of the image specified in the ``url`` parameter.\n\n``height`` (required)\n    The height in pixels of the image specified in the ``url`` parameter.\n\n\n###The video type\n\nThis type is used for representing playable videos. The following parameters\nare defined:\n\n``html`` (required)\n    The HTML required to embed a video player. The HTML should have no padding\n    or margins. Consumers may wish to load the HTML in an off-domain iframe to\n    avoid XSS vulnerabilities.\n\n``width``\n    The width in pixels required to display the HTML.\n\n``height``\n    The height in pixels required to display the HTML.\n\n\n###The link type\n\nResponses of this type allow a provider to return any generic embed data (such\nas title and author_name), without providing either the url or html parameters.\nThe consumer may then link to the resource, using the URL specified in the\noriginal request.\n\n###The rich type\n\nThis type is used for rich HTML content that does not fall under one of the\nother categories. The following parameters are defined:\n\n``html`` (required)\n    The HTML required to display the resource. The HTML should have no padding\n    or margins. Consumers may wish to load the HTML in an off-domain iframe to\n    avoid XSS vulnerabilities. The markup should be valid XHTML 1.0 Basic.\n\n``width``\n    The width in pixels required to display the HTML. \n\n``height``\n    The height in pixels required to display the HTML. \n\n\n\nError Codes\n----------------\n\n###JSON or XML Requests\n\n\n400 Bad Request\n  * Required \"url\" parameter is missing.\n  * Either \"url\" or \"urls\" parameter is reqiured.\n  * Invalid URL format.\n  * Invalid \"maxheight\" parameter.\n  * Invalid \"maxwidth\" parameter.\n  * Invalid \"urls\" parameter, exceeded max count of 20.\n\n401 Unauthorized\n  * Invalid key or oauth_consumer_key provided: <key>, contact: support:::at:::embed.ly.\n  * The provided key does not support this endpoint: <key>, contact: support@embed.ly.\n  * URL is private or restricted.\n\n403 Forbidden\n  * This service requires an embedly key parameter, contact: support@embed.ly or sign up: http://embed.ly/signup.\n  * Invalid IP provided: <ip>, contact: support@embed.ly.\n  * Invalid referrer provided: <referrer>, contact: support@embed.ly.\n\n404 Not Found\n  URL Not Found or unable to be accessed by Embedly servers.\n  \n  ``Note``:  Error message will contain Upstream server response.\n\n500 Server issues\n   Embed.ly is having trouble with this url. Please try again or contact us, support@embed.ly.\n\n501 Not Implemented\n   Not implemented for format: acceptable values are ``{json or xml}``.\n\n503 Service Unavailable\n  ``Note``: This happens if our service is down, please contact us immediately: support@embed.ly.\n\n###JSONP Requests\n\nFormat\n    ``callbackFunction({\"url\": \"url with error\", \"error_code\": \"error code\",\n    \"error_message\": \"error message\", \"type\": \"error\"})``\n\nError Response\n    ``jsonp1273162787542({\"url\": \"http://flickr.com/embedly\", \"error_code\": 404, \"error_message\":\n    \"HTTP 404: Not Found\", \"type\": \"error\"})``\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Want to Try out the oEmbed API?\",\n  \"body\": \"Try out our handy [oEmbed API Explorer](http://embed.ly/docs/explore/oembed). It's awesome and will allow you to preview the response of any URL.\\n\\nGo to the [oEmbed API Explorer](http://embed.ly/docs/explore/oembed)\"\n}\n[/block]","excerpt":"oEmbed is Embedly’s basic offering, providing a simple API for embedding content from any URL. This method follows the oEmbed standard.","slug":"oembed","type":"get","title":"/1/oembed"}

get/1/oembed

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

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

url:
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.
urls:
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.
maxwidth:
integer
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.
maxheight:
integer
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.
width:
integer
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.
height:
integer
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.
format:
string
The response format – Accepted values: (xml, json)
wmode:
string
Will append the wmode value to the flash object. Possible values include window, opaque and transparent.
callback:
string
Returns a (jsonp) response format. The callback is the name of the javascript function to execute.
allowscripts:
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.
autoplay:
boolean
This will tell the video/rich media to automatically play when the media is loaded. Accepted values: (true, false) Default: false
words:
string50
The words parameter works by trying to split the description at the closest sentence to that word count
chars:
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.
luxe:
boolean0
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.
secure:
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.
scheme:
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.
title:
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)
description:
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)
meta_images:
boolean0
Will return only an image found in meta tags or an API response if set.

Examples


Result Format


Documentation

[block:api-header] { "type": "basic", "title": "Response Attributes" } [/block] ``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: <key>, contact: support@embed.ly. * The provided key does not support this endpoint: <key>, contact: support@embed.ly. * URL is private or restricted. 403 Forbidden * This service requires an embedly key parameter, contact: support@embed.ly or sign up: http://embed.ly/signup. * Invalid IP provided: <ip>, contact: support@embed.ly. * Invalid referrer provided: <referrer>, contact: support@embed.ly. 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, support@embed.ly. 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: support@embed.ly. ###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"})`` [block:callout] { "type": "warning", "title": "Want to Try out the oEmbed API?", "body": "Try out our handy [oEmbed API Explorer](http://embed.ly/docs/explore/oembed). It's awesome and will allow you to preview the response of any URL.\n\nGo to the [oEmbed API Explorer](http://embed.ly/docs/explore/oembed)" } [/block]