Wistia and oEmbed

Grab embed codes using your video's URL with oEmbed, an easy API to implement with Wistia.

🛠️

Glitch

Try the oEmbed API instantly: Wistia oEmbed Example.

The Endpoint

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

Currently, our oEmbed endpoint recognizes two URL formats:

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:

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 https://home.wistia.com/medias/e4a27b971d in JSON format:

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

This returns:

{
  "version":"1.0",
  "type":"video",
  "html":"<iframe src=\"https://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":"https://embed-ssl.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: https://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:

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:

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

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

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

We'll URL-encode this request:

https%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 "https://fast.wistia.com/oembed.json?url=http%3A%2F%2Fexplanatoryvideos-1.wistia.com%2Fmedias%2F5u2svaqmbt%26embedType%3Dseo%26width%3D593"

This returns:

{
  "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":"https://embed-ssl.wistia.com/deliveries/2d2c14e15face1e0cc7aac98ebd5b6f040b950b5.jpg?image_crop_resized=640x360",
  "thumbnail_width":640,
  "thumbnail_height":360,
  "duration":16.43
}

Live Event Registration Form Embed Example

Instead of the URL to a public media, you’ll want to use the url for a live event.
E.g. https://home.wistia.com/live/abcd1234 or https://home.wistia.com/live/events/abcd1234

An additional query param, embedType, is required. For the registration form, you’ll want to pass “registration” as the embedType.

Example request:

curl "<https://fast.wistia.com/oembed?url=http%3A%2F%2Fhome.wistia.com%2Flive%2Fabcd1234&embedType=registration">

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.

var baseUrl = "https://fast.wistia.com/oembed/?url=";
var accountUrl = escape("https://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:

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.

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 folks!