Wistia

to the tippy ↑

Stats API

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!

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

wistia.json
1
2
3
4
5
  {
    "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

example_json.json
1
2
3
4
5
6
{
  "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

example_json_response.json
1
2
3
4
5
6
7
8
9
{
  "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

example_json_response.json
1
2
3
4
5
{
  "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

example_json_response.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[
  {
    "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

example_json_response.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "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.
email 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

example_json_response.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
[
  {
    "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

example_json_response.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "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:

heatmap_example.html
1
<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>