Stats 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

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.

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

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:

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

The Response

The response will be an array of objects. Each object represents a single visitor with the following fields:

Fields

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:

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

The Response

The response will be an array of objects. Each one represents a single viewing session (event) and has the following fields:

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>