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!
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.
Our oEmbed endpoint is:
Currently, our oEmbed endpoint recognizes three URL formats:
|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.
If you're looking to automatically detect Wistia URLs and run them against our endpoint, we recommend using this regular expression:
Or if you don't speak regex, here's what we're matching:
1 2 3 4
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:
Get the embed code and some information for a video at
http://home.wistia.com/medias/e4a27b971d in JSON format:
1 2 3 4 5 6 7 8 9 10 11 12 13
If you're looking for XML instead of JSON, use:
For all the fine details about the options supported, see the official oEmbed spec.
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:
|embedType||string|| Only applicable to videos and playlists. Accepts
|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.|
|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
(or any combination of those), the other dimensions in the resulting embed
code may change so that the video's aspect ratio is preserved.
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.
In this example, we'll request an
First, the media URL we'll request:
Next, we'll add the parameters for our request:
We'll URL-encode this request:
We URL-encoded this request, because we want the parameters
handle passed along as part of the url param, not at the top level of the oembed endpoint.
And now use the oEmbed endpoint:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
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.
1 2 3 4 5 6 7
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:
1 2 3
Finally, we'll setup something to call these functions for our
media hashed id:
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!
- If an invalid URL (one that doesn't match our regular expression above)
is given, the endpoint will return
404 Not Found.
- If an unparseable URL is given in the url param, the endpoint will return
404 Not Found.
- If a media is found, but failed to process, the endpoint will return
404 Not Found.
- If a media is found but has no available embed code, the endpoint will
501 Not Implemented. Video, Image, Audio, and Document files all currently implement oembeds. This will also occur if the video is not finished processing.
- 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!