Stats API
Learn how to access your stats via our API.
Ever looked at your Wistia heatmaps and wished you could show them to other people with ease? Ever looked at your Wistia heatmaps and wished that they were built out of purple cats instead of red, yellow, and green bars?
Want to figure out which of your Wistia videos your users have already viewed and recommend them ones they haven’t so they don’t get bored?
Want to make sure you purposely recommend the same videos repeatedly until they’re annoyed enough to convert?
Look no further, developers: the Wistia Stats API has you covered.
Account
Account: Show
The stats API allows you to retrieve some account-wide information. Don’t buy a nice car to overcompensate; instead, show off how many hours of your video have been played! Or, celebrate when you reach a certain landmark.
The Request
In order to tell Wistia that you want stats for your account, issue a GET request to the following URL:
GET https://api.wistia.com/v1/stats/account.json
The Response
Field | Description |
---|---|
load_count | The total number of times all of the videos from this account have been loaded. |
play_count | The total number of times all of the videos from this account have been played. |
hours_watched | The total amount of time spent watching all of the videos in this account. |
Example JSON Response
Status: 200 OK
{
"load_count": 1000,
"play_count": 400,
"hours_watched": 21.9
}
Project
Project: Show
The stats API allows you to retrieve information about all of the videos in a particular project. We know you like it when we let you get specific.
The Request
In order to retrieve stats for a project, issue a GET request to the following URL (you can find the Project ID in the URL for that project):
GET https://api.wistia.com/v1/stats/projects/[project-id].json
The Response
The response will come back as a single object representing the stats for this project.
Field | Description |
---|---|
load_count | The total number of times the videos in this project have been loaded. |
play_count | The total number of times the videos in this project have been played. |
hours_watched | The total time spent viewing the videos in this project. |
number_of_videos | The total number of videos in this project. |
Example JSON Response
Status: 200 OK
{
"load_count": 5498,
"play_count": 3942,
"hours_watched": 59.8,
"number_of_videos": 8,
}
Media
Media: Show
The Wistia stats API can be used to retrieve stats for any given video. Ever wanted to entice that special someone (or those hundreds of special someones viewing your page) to watch your video? Win their heart by displaying impressive data like your engagement rate. Or, give away a puppy to the thousandth viewer of your video. We heard you can 3D print those now.
The Request
In order to get stats for a video, issue a GET request to the following URL (you can find the Media ID in the URL for that media):
GET https://api.wistia.com/v1/stats/medias/[media-id].json
The Response
Field | Description |
---|---|
load_count | The total number of times this video has been loaded. |
play_count | The total number of times this video has been played. |
play_rate | The percentage of visitors who clicked play (between 0 and 1). |
hours_watched | The total time spent watching this video. |
engagement | The average percentage of the video that gets viewed (between 0 and 1). |
visitors | The total number of unique people that have loaded this video. |
actions | The stats for this video’s Turnstile, Annotation, and Call to Action. |
Example JSON Response
Status: 200 OK
{
"load_count": 100,
"play_count": 80,
"play_rate": 0.54,
"hours_watched": 21.9,
"engagement": 0.89,
"visitors": 94,
"actions": [{ "type": "Call to Action", "action_count": 24, "impression_count": 84, "rate": 0.286 }]
}
Media: Engagement
Using the stats API, you can retrieve the data used to construct the engagement graphs at the top of the stats page for any video in Wistia.
The Request
GET https://api.wistia.com/v1/stats/medias/[media-id]/engagement.json
Parameters
This method does not take any parameters besides the media-id that is already specified in the URL.
The Response
The response will come back as a single object that represents the main engagement data:
Field | Description |
---|---|
engagement | The percentage of the video that was viewed, averaged across all viewing sessions. |
engagement_data | An array which can be used as the data source for creating an engagement graph. Normally, each cell in the array represents how many times 1 second of the video has been viewed. However, for longer form content (over 1000 seconds), the array will be scaled down to 1000 items, with each item representing more than 1 second of playback. |
rewatch_data | An array which can be used for creating the rewatch block on an engagement graph. Normally, each cell in the array represents how many times 1 second of the video has been viewed. However, for longer form content (over 1000 seconds), the array will be scaled down to 1000 items, with each item representing more than 1 second of playback. |
Example JSON Response
Status: 200 OK
{
"engagement": 0.75,
"engagement_data": [ 154, 152, 152, 151, 148, ... ],
"rewatch_data": [ 13, 17, 19, 19, 15, ... ]
}
Visitors
Visitors: List
This method allows you to retrieve a list of visitors that have watched videos in your account.
The Request
GET https://api.wistia.com/v1/stats/visitors.json
Parameters
Parameter | Description |
---|---|
page | The page of results that you want, based on the per_page parameter. |
per_page | The maximum number of results to return. This value is capped at 100. |
filter | This parameter is optional and can take one of three values: ’has_name' or ’has_email' or ’identified_by_email_gate'. Without the parameter, all visitors are returned. For the value ’has_name', only named visitors are returned. For the value ’has_email', only visitors with an email address are returned. For the value ’identified_by_email_gate', only visitors who have entered their email in a video email gate are returned. |
search | If this parameter is specified, only visitors whose name or email address contains the exact given value will be returned. |
The Response
The response will be an array of objects. Each object represents a single visitor with the following fields:
Fields
Field | Description |
---|---|
visitor_key | This is a unique identifier for the visitor. |
created_at | When the visitor was created - i.e. when they first loaded a video in the account. |
last_active_at | The last time the visitor played a video. |
last_event_key | The event key which can be used to retrieve the information about what happened when they last played a video. |
load_count | The total number of videos that have been loaded (but not necessarily viewed) by this visitor. |
play_count | The total number of videos that have been viewed by this visitor. |
identifying_event_key | The key of the event that was used to identify this visitor. Some examples: the first turnstile this visitor entered or the first load event that was tagged with this visitor info via wemail. |
visitor_identity | An object with 3 fields (name, email, and org) that represents the available identity info for this visitor. |
user_agent_details | An object with 4 fields: browser (e.g. ’Chrome'), browser_version (e.g. '46'), platform (e.g. ’mac'), and mobile (boolean value stating whether the visitor was on their mobile phone.) |
Example JSON Response
Status: 200 OK
[
{
"visitor_key": "E4E7613B5C24CB0F1F7C0A1E4E874635E752263E",
"created_at": "2012-12-12T01:51:36Z",
"last_active_at": "2012-12-12T03:15:56Z",
"last_event_key": "1355282055737f0.4801975437439978",
"load_count": 3,
"play_count": 2,
"identifying_event_key": 1390862572596e0.8447021404281259,
"visitor_identity": {
"name": "Jim",
"email": "jim@example.com",
"org": {
"name": "Jeff's Lemonade",
"title": "Expert lemon squeezer"
}
},
"user_agent_details": {
"browser": "Chrome",
"browser_version": "45",
"platform": "mac",
"mobile": false
}
},
{
"visitor_key": "9DC9D7F525236E25E27E9743C0524DB0F02C703D",
"created_at": "2011-12-15T22:20:08Z",
"last_active_at": "2012-12-12T03:13:52Z",
"last_event_key": "1355282030102f0.8788125906139612",
"load_count": 17,
"play_count": 9,
"identifying_event_key": null,
"visitor_identity": {
"name": null,
"email": null,
"org": {
"name": null,
"title": null
}
},
"user_agent_details": {
"browser": "Chrome",
"browser_version": "45",
"platform": "mac",
"mobile": false
}
}
]
Visitors: Show
This method allows you to retrieve the information for a single visitor.
The Request
GET https://api.wistia.com/v1/stats/visitors/[visitor-key].json
Parameters
This method does not take any parameters besides the visitor-key that is already specified in the URL.
The Response
The response will be a single object representing the visitor’s information. It contains the following fields:
Field | Description |
---|---|
visitor_key | This is a unique identifier for the visitor. |
created_at | When the visitor was created - i.e. when they first loaded a video in the account. |
last_active_at | The last time the visitor played a video. |
last_event_key | The event key that can be used to retrieve the information about what happened when they last played a video. |
load_count | The total number of videos that have been loaded (but not necessarily viewed) by this visitor. |
play_count | The total number of videos that have been viewed by this visitor. |
visitor_identity | An object with 3 fields (name, email, and org) that represents the available identity info for this visitor. |
user_agent_details | An object with 4 fields: browser (e.g. ’Chrome'), browser_version (e.g. '46'), platform (e.g. ’mac'), and mobile (boolean value stating whether the visitor was on their mobile phone.) |
Example JSON Response
Status: 200 OK
{
"visitor_key": "E4E7613B5C24CB0F1F7C0A1E4E874635E752263E",
"created_at": "2012-12-12T01:51:36Z",
"last_active_at": "2012-12-12T03:15:56Z",
"last_event_key": "1355282055737f0.4801975437439978",
"load_count": 3,
"play_count": 2,
"visitor_identity": {
"name": "Jim",
"email": "jim@example.com",
"org": {
"name": "Jim's Lemonade",
"title": "Expert lemon squeezer"
}
},
"user_agent_details": {
"browser": "Chrome",
"browser_version": "45",
"platform": "mac",
"mobile": false
}
}
Events
Events: List
This method allows you to retrieve a list of events (viewing sessions) from your account.
The Request
GET https://api.wistia.com/v1/stats/events.json
Parameters
Parameter | Description |
---|---|
media_id | An optional parameter specifying the video for which you would like to retrieve events. |
visitor_key | An optional parameter specifying the visitor for which you would like to retrieve events. |
per_page | The maximum number of events to retrieve. This number is capped at 100. If you need to get more than 100 events, please issue multiple requests. |
page | The page of events to get data from, based on the per_page parameter. |
start_date | An optional parameter indicating that events should only be returned after the given date. Takes the format '2012–11–25'. |
end_date | An optional parameter indicating that events should only be returned before the given date. Takes the format '2012–11–25'. |
The Response
The response will be an array of objects. Each one represents a single viewing session (event) and has the following fields:
Field | Description |
---|---|
received_at | The date and time that the event happened. |
event_key | The ID for that event. |
visitor_key | The id of the visitor, which can be used to retrieve further information about them. |
embed_url | The URL of the page where the video was viewed. |
percent_viewed | The decimal number denoting how much of the video was watched during this session (0 to 1). |
ip | The viewer’s IP address. |
org | The organization that the IP address belongs to. |
country | The viewer’s country, based on IP. |
region | The viewer’s region, based on IP. |
city | The viewer’s city, based on IP. |
lat | The latitude of the viewer’s IP. |
lon | The longitude of the viewer’s IP. |
The viewer’s email address, if available. | |
media_id | An identifier indicating which video was watched. |
media_url | The video’s URL in the Wistia account. |
media_name | The name of the video. |
iframe_heatmap_url | The URL of an HTML page that will render the heatmap for this event. |
Example JSON Response
Status: 200 OK
[
{
"received_at": "2014-01-27T22:42:53Z",
"event_key": "1390862572596e0.8447021404281259",
"ip": "64.95.172.26",
"country": "US",
"region": "WA",
"city": "Seattle",
"lat": 47.6103,
"lon": -122.334,
"org": "Onvia.com",
"email": null,
"percent_viewed": 0.22457664233576624,
"embed_url": "http://wistia.github.io/demobin/post-roll-video-play/",
"conversion_type": "",
"conversion_data": {
"email": "test@wistia.com",
"first_name" : "Jeff",
"last_name" : "Vincent"
},
"iframe_heatmap_url": "https://api.wistia.com/v1/stats/events/1390862572596e0.8447021404281259/iframe.html?public_token=xxxxxx",
"visitor_key": "B6D1F47963577AF26697138FAB75BD1B7086697B",
"media_id": "993554ba94",
"media_name": "How They Work - Help Scout",
"media_url": "https://jeff.wistia.com/medias/993554ba94",
"thumbnail": {
"url": "http://embed.wistia.com/deliveries/48fbdd30054000aa548938ef436dfb1a190d34c5.bin",
"width": 640,
"height": 360,
"fileSize": 32720,
"contentType": "image/jpeg",
"type": "StillImageFile"
}
},
{
"received_at": "2014-01-27T20:54:31Z",
"event_key": "1390856239396e0.3702384910728902",
"ip": "186.137.141.112",
"country": "AR",
"region": "07",
"city": "Buenos Aires",
"lat": -34.5875,
"lon": -58.6725,
"org": "CABLEVISION S.A.",
"email": null,
"percent_viewed": 0.04356993736951984,
"embed_url": "http://wistia.github.io/demobin/multiple-plays-at-once/",
"conversion_type": "",
"conversion_data": {
"email": "test@wistia.com",
"first_name" : "Jeff",
"last_name" : "Vincent"
},
"iframe_heatmap_url": "https://api.wistia.com/v1/stats/events/1390856239396e0.3702384910728902/iframe.html?public_token=xxxxxx",
"visitor_key": "7C1125427A252C6DE06FDC2B007712911DAF17B7",
"media_id": "r2wybv7xr0",
"media_name": "2012 Recap",
"media_url": "https://jeff.wistia.com/medias/r2wybv7xr0",
"thumbnail": {
"url": "http://embed.wistia.com/deliveries/34d01c07ff2da906b092c8ba1c75b0c345006340.bin",
"width": 1280,
"height": 720,
"fileSize": 191752,
"contentType": "image/jpeg",
"type": "StillImageFile"
}
}
]
Events: Show
This method gives you the information about a single event from your account.
The Request
GET https://api.wistia.com/v1/stats/events/[event-key].json
Parameters
This method does not take any parameters other than the event key already specified in the URL.
The Response
The response will be a single object representing the information about the event. The format and fields of this object will be the same as can be found in the Events: List method.
Example JSON Response
Status: 200 OK
{
"received_at": "2014-01-27T22:42:53Z",
"event_key": "1390862572596e0.8447021404281259",
"ip": "64.95.172.26",
"country": "US",
"region": "WA",
"city": "Seattle",
"lat": 47.6103,
"lon": -122.334,
"org": "Onvia.com",
"email": null,
"percent_viewed": 0.22457664233576624,
"embed_url": "http://wistia.github.io/demobin/post-roll-video-play/",
"conversion_type": "",
"conversion_data": {
"email": "test@wistia.com",
"first_name" : "Jeff",
"last_name" : "Vincent"
},
"iframe_heatmap_url": "https://api.wistia.com/v1/stats/events/1390862572596e0.8447021404281259/iframe.html?public_token=xxxxxxx",
"visitor_key": "B6D1F47963577AF26697138FAB75BD1B7086697B",
"media_id": "993554ba94",
"media_name": "How They Work - Help Scout",
"media_url": "https://jeff.wistia.com/medias/993554ba94",
"thumbnail": {
"url": "http://embed.wistia.com/deliveries/48fbdd30054000aa548938ef436dfb1a190d34c5.bin",
"width": 640,
"height": 360,
"fileSize": 32720,
"contentType": "image/jpeg",
"type": "StillImageFile"
}
}
Events: Heatmap
You can get the heatmap for any event by constructing the following URL:
GET https://api.wistia.com/v1/stats/events/[event-key]/iframe.html?public_token=[public_token]
Replace the <event-key>
token with the event_key that indicates which heatmap you would like to see. You can get the <event-key>
value from other parts of this API or from the Wistia player itself.
Make sure you also provide your account’s <public_token>
as a parameter. You can find your <public_token>
by clicking on API in your Account Settings.
This URL is meant to be used as the target of an iframe which can then be used to render the heatmap within your own pages.
Here is an example heatmap embedded right into this page:
Here is the code that we used to embed the heatmap:
<iframe src="https://api.wistia.com/v1/stats/events/1355283144880f0.12204939918592572/iframe.html?public_token=p5j1mnpakv" height="70" width="100%" style="border: solid 2px black;"></iframe>