oEmbed is an open standard that allows websites and tools to display embedded content such as a video simply by providing a URL. Instead of manually constructing embed code, an oEmbed consumer (e.g. a CMS, WordPress, or a service like Embed.ly) sends a request to the oEmbed endpoint and receives ready-to-use embed code in return.
The Blue Billywig oEmbed Service accepts a clip URL and returns embed code along with metadata about the video, such as its title, dimensions, and thumbnail. You can paste the returned html field directly into a web page to display the video player.
1.0 | oEmbed JSON Output
The default response is a JSON object containing the embed code and video metadata. All parameters are passed as query string parameters, of which url is the only required one.
Request
https://<publication>.bbvms.com/oembed/?url=<encoded-clip-url>[&optional-parameters]The url value must be URL-encoded. It should point to a clip page in the following format:
https://<publication>.bbvms.com/p/<playout>/c/<clipId>.htmlA playout is a Blue Billywig player configuration that defines the player’s appearance and behaviour. The default playout is used when no specific playout is required.
Example request
https://yourcompanyname.bbvms.com/oembed/?url=https%3A%2F%2Fbbvms.com%2Fpub%2Fyourcompanyname%2Fp%2Fdefault%2Fc%2F6104413.html&width=720&height=380&thumbWidth=720&thumbHeight=380&format=Parameters
| Parameter | Description |
|---|---|
| Required | |
url | URL-encoded link to the clip page: https://<publication>.bbvms.com/p/<playout>/c/<clipId>.html |
| Optional | |
width | Width of the embed in pixels. If only one dimension is provided, the other is calculated automatically to maintain the original aspect ratio. |
height | Height of the embed in pixels. If only one dimension is provided, the other is calculated automatically to maintain the original aspect ratio. |
thumbWidth | Width of the thumbnail in pixels |
thumbHeight | Height of the thumbnail in pixels |
format | Response format: json (default) or xml |
oEmbedMode | Embed type returned in the html field: javascript (default) or iframe. Use iframe for compatibility with third-party oEmbed consumers such as Embed.ly. |
1.1 | Response Fields
The response contains the following fields:
| Field | Description |
|---|---|
type | Always video |
version | Always 1.0 |
provider_name | Name of the provider (see Section 3.0) |
provider_url | URL of the provider (see Section 3.0) |
title | Title of the clip |
author_name | Author name associated with the clip |
width | Width of the embed in pixels |
height | Height of the embed in pixels |
thumbnail_url | URL of the clip thumbnail |
thumbnail_width | Width of the thumbnail in pixels |
thumbnail_height | Height of the thumbnail in pixels |
html | The embed code to insert into your web page |
Example response
{
"type": "video",
"version": "1.0",
"provider_name": "Blue Billywig",
"provider_url": "https://www.bluebillywig.com/",
"title": "Sport Event",
"author_name": "Blue Billywig",
"width": 720,
"height": 380,
"thumbnail_url": "https://yourcompanyname.bbvms.com/mediaclip/6104413/pthumbnail/720/380.jpg",
"thumbnail_width": 720,
"thumbnail_height": 380,
"html": "<script type="text/javascript" src="https://yourcompanyname.bbvms.com/p/default/c/6104413.js?&width=720&height=380"></script>"
}2.0 | oEmbed XML Output
To obtain an XML response instead of the default JSON response, add format=xml to the request.
3.0 | Resource Provider
The provider_name and provider_url fields in the response identify the video provider; for example, your company name and website. These fields will be empty unless they are configured for your publication.
To have these fields set up, contact our Support Team at support@bluebillywig.com.