Wistia

to the tippy ↑

Wistia and oEmbed

Warning: You are heading into developer territory!

Our APIs are designed for programmers. If our APIs were a ski trail, they'd be a nice blue cruiser - anyone can do it, but expect to fall a few times if you don't know what you're doing!

If you're new to web development, we recommend taking a lesson before you hit our slopes. Try a class from Frontend Masters or Skillshare!

oEmbed is a simple API to get information about embedded content on a URL.

For Wistia, it's a great way to programmatically get embed codes for videos if you have their URLs.

Glitch

Try the oEmbed API instantly: Wistia oEmbed Example.

The Endpoint

Our oEmbed endpoint is: http://fast.wistia.com/oembed

Currently, our oEmbed endpoint recognizes three URL formats:

Type Example URL
iframe embed code URLs http://fast.wistia.com/embed/iframe/b0767e8ebb?version=v1&controlsVisibleOnLoad=true&playerColor=aae3d8
iframed playlist URLs http://fast.wistia.com/embed/playlists/fbe3880a4e?theme=trime&version=v1&videoOptions%5BvideoHeight%5D=360&videoOptions%5BvideoWidth%5D=640
Public media URLs http://home.wistia.com/medias/e4a27b971d

It's likely we'll add more URLs to this list in the future.


The Regex

If you're looking to automatically detect Wistia URLs and run them against our endpoint, we recommend using this regular expression:

/https?:\/\/(.+)?(wistia.com|wi.st)\/(medias|embed)\/.*/

Or if you don't speak regex, here's what we're matching:

thumbnail.html
1
2
3
4
http(s)://*wistia.com/medias/*
http(s)://*wistia.com/embed/*
http(s)://*wi.st/medias/*
http(s)://*wi.st/embed/*

Note, it's likely we'll add support for more URLs in the future so feel free to use a more general regular expression so you don't miss out on future enhancements! Perhaps this:

/https?:\/\/(.+)?(wistia.com|wi.st)\/.*/


An Example

Get the embed code and some information for a video at http://home.wistia.com/medias/e4a27b971d in JSON format:

curl "http://fast.wistia.com/oembed?url=http%3A%2F%2Fhome.wistia.com%2Fmedias%2Fe4a27b971d"

This returns:

return.json
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "version":"1.0",
  "type":"video",
  "html":"<iframe src=\"http://fast.wistia.net/embed/iframe/e4a27b971d?version=v1&videoHeight=360&videoWidth=640\" allowtransparency=\"true\" frameborder=\"0\" scrolling=\"no\" class=\"wistia_embed\" name=\"wistia_embed\" width=\"640\" height=\"360\"></iframe>",
  "width":640,
  "height":360,
  "provider_name":"Wistia, Inc.",
  "provider_url":"https://wistia.com",
  "title":"Brendan - Make It Clap",
  "thumbnail_url":"http://embed.wistia.com/deliveries/2d2c14e15face1e0cc7aac98ebd5b6f040b950b5.jpg?image_crop_resized=100x60",
  "thumbnail_width":100,
  "thumbnail_height":60
}

If you're looking for XML instead of JSON, use: http://fast.wistia.com/oembed.xml

For all the fine details about the options supported, see the official oEmbed spec.


Parameters

Our endpoint supports all the options detailed at oembed.com.

The required url parameter that's passed in supports all the options detailed in the Embed Options Documentation.

We also accept some additional parameters that can change the output of the embed code:

Name Type Description
callback string Only applicable to JSON requests. When specified, JSON is wrapped in a javascript function given by the callback param. This is to facilitate JSONP requests.
embedType string Only applicable to videos and playlists. Accepts iframe, async, async_popover, playlist_iframe, playlist_api, playlist_popver, and open_graph_tags (videos only).
width integer The requested width of the video embed. Defaults to the native size of the video or 360, whichever is smaller.
height integer The requested height of the video embed. Defaults to the native size of the video or 640, whichever is smaller.
handle string Only applicable to "api", "seo", and "playlist_api" embed types. Sets the javascript handle. Default is wistiaEmbed for medias and wistiaPlaylist for playlists.
popoverHeight integer Only applicable to "popover" embed type. The requested height of the popover. Defaults to maintain the correct aspect ratio, with respect to the width.
popoverWidth integer Only applicable to "popover" embed type. The requested width of the popover. Defaults to 150.

If given a width, height, maxwidth, or maxheight parameter (or any combination of those), the other dimensions in the resulting embed code may change so that the video's aspect ratio is preserved.

Note

These parameters are attached to the Wistia media URL, and not the oEmbed call. So they must be URL-encoded to travel with the Wistia URL.

Example

In this example, we'll request an API embed code type, with the javascript handle oEmbedVideo:

First, the media URL we'll request:

http://home.wistia.com/medias/e4a27b971d

Next, we'll add the parameters for our request:

http://home.wistia.com/medias/e4a27b971d?embedType=api&handle=oEmbedVideo

We'll URL-encode this request:

http%3A%2F%2Fhome.wistia.com%2Fmedias%2Fe4a27b971d%3FembedType%3Dapi%26handle%3DoEmbedVideo

Note

We URL-encoded this request, because we want the parameters embedType and handle passed along as part of the url param, not at the top level of the oembed endpoint.

And now use the oEmbed endpoint:

curl "http://fast.wistia.com/oembed.json?url=http%3A%2F%2Fexplanatoryvideos-1.wistia.com%2Fmedias%2F5u2svaqmbt%26embedType%3Dseo%26width%3D593"

This returns:

return.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "version":"1.0",
  "type":"video",
  "html":"<div id=\"wistia_e4a27b971d\" class=\"wistia_embed\" style=\"width:640px;height:360px;\" data-video-width=\"640\" data-video-height=\"360\">&nbsp;</div>\n<script charset=\"ISO-8859-1\" src=\"//fast.wistia.com/assets/external/E-v1.js\"></script>\n<script>\noEmbedVideo = Wistia.embed(\"e4a27b971d\", {\n  version: \"v1\",\n  videoWidth: 640,\n  videoHeight: 360\n});\n</script>",
  "width":640,
  "height":360,
  "provider_name":"Wistia, Inc.",
  "provider_url":"https://wistia.com",
  "title":"Brendan - Make It Clap",
  "thumbnail_url":"http://embed.wistia.com/deliveries/2d2c14e15face1e0cc7aac98ebd5b6f040b950b5.jpg?image_crop_resized=640x360",
  "thumbnail_width":640,
  "thumbnail_height":360,
  "duration":16.43
}

Using JSONP

JSONP is a javascript technique used to get information from a server that is not the same origin as your current domain. This means they can avoid cross-domain security issues.

In this example, we'll write some javascript to pull data for our video against the oEmbed endpoint, utilizing JSONP. Then, we'll manipulate the data returned to embed the thumbnail image.

Given the oEmbed base URL, your account URL, and a media hashed id, we can use the jQuery getJSON function to call against the oEmbed endpoint to return the video data.

Note this function also takes a callback function as a parameter. We'll set up that callback function next.

playlist_api.js
1
2
3
4
5
6
7
var baseUrl = "http://fast.wistia.com/oembed/?url=";
var accountUrl = escape("http://home.wistia.com/medias/");
var mediaHashedId = "01a1d9f97c";

function getThumbnailUrl(hashedId, callback) {
  $.getJSON(baseUrl + accountUrl + hashedId + "&format=json&callback=?", callback);
}

This function will return a JSON data object, and pass it to our callback function, which will parse the JSON and log the thumbnail URL. Let's write that callback function now:

playlist_api.js
1
2
3
function parseJSON(json) {
  console.log(json.thumbnail_url);
};

Finally, we'll setup something to call these functions for our media hashed id:

getThumbnailUrl(mediaHashedId, parseJSON);


Working With The Thumbnail

Part of the JSON returned by the oEmbed is the thumbnail_url. This URL is a direct link to the thumbnail image asset. If your implementation involves using the thumbnail image (i.e. building your own 'popover' embeds, displaying your own play button, etc.) you should use this thumbnail image, which by default has no Wistia play button overlaid on it.

See our working with Wistia images guide for more info!


Troubleshooting

  1. If an invalid URL (one that doesn't match our regular expression above) is given, the endpoint will return 404 Not Found.
  2. If an unparseable URL is given in the url param, the endpoint will return 404 Not Found.
  3. If a media is found, but failed to process, the endpoint will return 404 Not Found.
  4. If a media is found but has no available embed code, the endpoint will return 501 Not Implemented. Video, Image, Audio, and Document files all currently implement oembeds. This will also occur if the video is not finished processing.
  5. If a playlist is found but has no videos, the endpoint will return 501 Not Implemented.

Make Your Life Easier

If you're contemplating doing an oEmbed implementation with Wistia (or any oEmbed provider for that matter), we strongly recommend checking out Embedly. By integrating with them you'll have immediate access to over 100 oEmbed providers. They also have great documentation and ready-made libraries for every popular language, plus they're just nice guys!