API: Statistics

In this page

This page documents every statistics endpoint in detail. For a condensed, scannable list of all statistics endpoints grouped by resource, see the Quick Reference.

IAB Certified Statistics

Our statistics are officially certified by IAB Technology Lab (IAB). Adhering to the IAB podcast measurement guidelines helps us deliver clearer insight into the users who listen to your podcast episodes and has improved the way our statistics system detects fake plays and downloads originated by bots. The figures you see in your statistics now exclude users who have listened to less than one minute of an episode.

CSV Export

Most statistics endpoints on this page can also return their data as a CSV file: add .csv to the end of the endpoint path (e.g. GET /v2/shows/SHOW-ID/statistics/plays.csv) and pass the same parameters as the regular JSON request. Endpoints that support this are marked with a “CSV export” note under their Endpoints list below.

Overall Statistics

Endpoints

GET /v2/organizations/ORGANIZATION-ID/statistics
GET /v2/users/USER-ID/statistics
GET /v2/shows/SHOW-ID/statistics
GET /v2/episodes/EPISODE-ID/statistics

Response

The Statistics API always returns a list of objects with the following fields:

Property Type Description
plays_count Number The number of all-time plays (both live and on demand).
Available in organizations, users, shows, and episodes statistics.
downloads_count Number The number of all-time downloads.
Available in organizations, users, shows, and episodes statistics.
plays_ondemand_count Number The number of all-time on demand plays.
Available in organizations, users, shows, and episodes statistics.
plays_live_count Number The number of all-time live plays.
Available in organizations, users, shows, and episodes statistics.
likes_count Number The number of all-time likes.
Available in users, shows, and episodes statistics.
episodes_count Number The number of listenable episodes.
Only available in users and shows statistics.
shows_count Number The number of shows created.
Only available in users statistics.
followers_count Number The current number of followers.
Only available in users statistics.
chapters_count Number The current number of chapters.
Only available in episodes statistics.
messages_count Number The current number of messages.
Only available in episodes statistics.
organization Organization The organization details.
Available in organizations statistics.
user User The user details.
Available in users statistics.
show Show The show details.
Available in shows statistics.
episode Episode The episode details.
Available in episodes statistics.

Retrieving an Organization’s Overall Statistics

GET /v2/organizations/ORGANIZATION-ID/statistics

Authenticated: yes

This API returns a JSON object containing an organization’s all-time overall statistics.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/42/statistics"
{
    "response": {
        "statistics": {
            "plays_count": 47,
            "plays_ondemand_count": 40,
            "plays_live_count": 7,
            "downloads_count": 10,
            "organization": {
                "organization_id": 42,
                "name": "Mondadori",
                "image_url": null,
                "image_original_url": null,
                "slug": "mondadori",
                "site_url": "https://www.spreaker.com/organization/mondadori--42"
            }
        }
    }
}

Retrieving a User’s Overall Statistics

This endpoint is deprecated and will be removed in a future release. Please use the show or organization based endpoints instead. 

GET /v2/users/USER-ID/statistics

Authenticated: yes

This API returns a JSON object containing a user’s all-time overall statistics.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/1/statistics"
{
    "response": {
        "statistics": {
            "plays_count": 47,
            "plays_ondemand_count": 40,
            "plays_live_count": 7,
            "shows_count": 10,
            "episodes_count": 20,
            "likes_count": 15,
            "downloads_count": 10,
            "followers_count": 40,
            "user": {
                "user_id": 1,
                "fullname": "Marco Pracucci",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/a9c98be54e22d5bad6a951e1c4d04ade.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/a9c98be54e22d5bad6a951e1c4d04ade.jpg",
            }
        }
    }
}

Retrieving a Show’s Overall Statistics

GET /v2/shows/SHOW-ID/statistics

Authenticated: yes

This API returns a JSON object containing a show’s all-time overall statistics.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/1433865/statistics"
{
    "response": {
        "statistics": {
            "title": "Super Show",
            "plays_count": 47,
            "plays_ondemand_count": 40,
            "plays_live_count": 7,
            "episodes_count": 20,
            "downloads_count": 10,
            "show": {
                "show_id": 1433865,
                "title": "Spreaker Live Show with Rob Greenlee",
                "site_url": "https://www.spreaker.com/show/spreaker-live-show",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                "author_id": 8114541
            }
        }
    }
}

Retrieving an Episode’s Overall Statistics

GET /v2/episodes/EPISODE-ID/statistics

Authenticated: yes

This API returns a JSON object containing an episode’s all-time overall statistics.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/321/statistics"
{
    "response": {
        "statistics": {
            "plays_count": 47,
            "plays_ondemand_count": 40,
            "plays_live_count": 7,
            "chapters_count": 10,
            "messages_count": 20,
            "likes_count": 15,
            "downloads_count": 10,
            "episode": {
                "episode_id": 8936994,
                "type": "RECORDED",
                "title": "SLSPM69: Marty Michael, Co-Founder of HeadGum Podcast Network",
                "duration": 1460430,
                "show_id": 1433865,
                "author_id": 8114541,
                "site_url": "https://www.spreaker.com/episode/8936994",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
                "published_at": "2016-07-07 16:47:54",
                "download_enabled": true,
                "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8936994.gz.json?v=2fAdf6",
                "show": {
                    "show_id": 1433865,
                    "title": "Spreaker Live Show with Rob Greenlee",
                    "site_url": "https://www.spreaker.com/show/spreaker-live-show",
                    "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                    "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                    "author_id": 8114541
                }
            }
        }
    }
}

Plays and Downloads Statistics

Plays and Downloads Statistics API makes a distinction between number of plays and number of downloads: if you are interested in learning more, you can consult this article in our Spreaker Help Center.

Endpoints

GET /v2/organizations/ORGANIZATION-ID/statistics/plays
GET /v2/users/USER-ID/statistics/plays
GET /v2/shows/SHOW-ID/statistics/plays
GET /v2/episodes/EPISODE-ID/statistics/plays

These endpoints also support CSV export.

Request Parameters

These are the request parameters for any Play Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
group Yes String The group-type to apply to the statistics. It can be day, week, or month.

Response

The Statistics API always returns a list of objects with the following fields:

Property Type Description
date A date string in the format YYYY-MM-DD The date the data is relative to, depending on the group-type:
day - the specific day the data relates to.
week - the first day (Sunday) of the week the data relates to.
month - the first day of the month the data relates to.
plays_count Number Number of plays (both live and on demand).
plays_live_count Number Number of plays while broadcasting live.
plays_ondemand_count Number Number of on demand plays.
downloads_count Number Number of downloads.

Retrieving an Organization’s Play Statistics

GET /v2/organizations/ORGANIZATION-ID/statistics/plays

Authenticated: yes

This API returns a JSON object containing statistics relative to all of an organization’s show and episode plays, according to a particular interval and grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/1/statistics/plays?from=2016-10-10&to=2016-10-12&group=day"
{
    "response": {
        "statistics": [
            {
                "date": "2016-10-10",
                "plays_count": 17,
                "plays_live_count": 3,
                "plays_ondemand_count": 14,
                "downloads_count": 20
            },
            {
                "date": "2016-10-11",
                "plays_count": 0,
                "plays_live_count": 0,
                "plays_ondemand_count": 0,
                "downloads_count": 0
            },
            {
                "date": "2016-10-12",
                "plays_count": 30,
                "plays_live_count": 4,
                "plays_ondemand_count": 26,
                "downloads_count": 50
            }
        ]
    }
}

Retrieving a User’s Play Statistics

This endpoint is deprecated and will be removed in a future release. Please use the organization, show or episode based endpoints instead. 

GET /v2/users/USER-ID/statistics/plays

Authenticated: yes

This API returns a JSON object containing statistics relative to all of a user’s show and episode plays, according to a particular interval and grouped by the requested group-type. The response has the same shape as the organization example above.

Retrieving a Show’s Play Statistics

GET /v2/shows/SHOW-ID/statistics/plays

Authenticated: yes

This API returns a JSON object containing a specific show’s play statistics, based on a certain interval and grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/123/statistics/plays?from=2016-10-10&to=2016-10-20&group=week"

Returns the same JSON shape as the organization example above.

Retrieving an Organization’s Users’ Total Play Statistics

GET /v2/organizations/ORGANIZATION-ID/users/statistics/plays/totals

Authenticated: yes

This API returns a paginated list of items containing total play statistics for each user owned by the ORGANIZATION-ID, based on a certain date interval.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/8114541/users/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=3&limit=3"

The response body is a paginated list of items.

{
  "response": {
    "items": [
      {
        "show_id": 1396918,
        "title": "Spreaker Live from NMX/NAB 2015",
        "is_deleted": false,
        "is_transferred": false,
        "plays_count": 38,
        "plays_live_count": 0,
        "plays_ondemand_count": 38,
        "downloads_count": 30
      },
      {
        "show_id": 1433865,
        "title": "Spreaker Live Show with Rob Greenlee",
        "is_deleted": false,
        "is_transferred": false,
        "plays_count": 0,
        "plays_live_count": 0,
        "plays_ondemand_count": 0,
        "downloads_count": 39
      },
      {
        "show_id": 1634369,
        "title": "Spreaker National Radio Ad Spots",
        "is_deleted": false,
        "is_transferred": false,
        "plays_count": 13,
        "plays_live_count": 2,
        "plays_ondemand_count": 11,
        "downloads_count": 2
      }
    ],
    "prev_url": "https://api.spreaker.com/v2/organizations/8114541/users/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=0&limit=3",
    "next_url": "https://api.spreaker.com/v2/organizations/8114541/users/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=6&limit=3"
  }
}

Retrieving a User’s Shows’ Total Play Statistics

This endpoint is deprecated and will be removed in a future release. Please use the organization based endpoint instead. 

GET /v2/users/USER-ID/shows/statistics/plays/totals

Authenticated: yes

This API returns a paginated list of items containing total play statistics for each show owned by the USER-ID, based on a certain date interval. The response has the same shape as the organization example above.

Retrieving a Show’s Episodes’ Total Play Statistics

GET /v2/shows/SHOW-ID/episodes/statistics/plays/totals

Authenticated: yes

This API returns a paginated list of items containing total play statistics for each episode belonging to the SHOW-ID, based on a certain date interval.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/1433865/episodes/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=3&limit=3"

Returns the same paginated shape as the organization example above, with each item keyed by episode_id instead of show_id.

Retrieving an Episode’s Play Statistics

GET /v2/episodes/EPISODE-ID/statistics/plays

Authenticated: yes

This API returns a JSON object containing a specific episode’s play statistics, based on a certain interval and grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/321/statistics/plays?from=2016-10-10&to=2016-11-02&group=month"

Returns the same JSON shape as the organization example above.

Likes Statistics

Endpoints

GET /v2/users/USER-ID/statistics/likes
GET /v2/shows/SHOW-ID/statistics/likes
GET /v2/episodes/EPISODE-ID/statistics/likes

These endpoints also support CSV export.

Request Parameters

These are the request parameters for Likes Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
group Yes String The group-type to apply to the statistics. It can be day, week or month.

Response

The Statistics API always returns a list of objects with the following fields:

Property Type Description
date A date string in the format YYYY-MM-DD The date the data is relative to, depending on the group-type:
day - the specific day the data relates to.
week - the first day (Sunday) of the week the data relates to.
month - the first day of the month the data relates to.
likes_count Number Number of likes obtained.

Retrieving a User’s Likes Statistics

This endpoint is deprecated and will be removed in a future release. Please use the show or episode based endpoints instead. 

GET /v2/users/USER-ID/statistics/likes

Authenticated: yes

This API returns a JSON object containing a user’s show and episode likes statistics, based on a certain interval and grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/1/statistics/likes?from=2016-10-10&to=2016-10-12&group=day"
{
    "response": {
        "statistics": [
            {
                "date": "2016-10-10",
                "likes_count": 12
            },
            {
                "date": "2016-10-11",
                "likes_count": 1
            },
            {
                "date": "2016-10-12",
                "likes_count": 4
            }
        ]
    }
}

Retrieving a Show’s Likes Statistics

GET /v2/shows/SHOW-ID/statistics/likes

Authenticated: yes

This API returns a JSON object containing a specific show’s likes statistics, based on a certain interval and grouped by the requested group-type.

Retrieving an Episode’s Likes Statistics

GET /v2/episodes/EPISODE-ID/statistics/likes

Authenticated: yes

This API returns a JSON object containing a specific episode’s likes statistics, based on a certain interval and grouped by the requested group-type.

Followers Statistics

Endpoints

GET /v2/users/USER-ID/statistics/followers

This endpoint also supports CSV export.

Request Parameters

These are the request parameters for Followers Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
group Yes String The group-type to apply to the statistics. It can be day, week or month.

Response

The Followers Statistics API always returns a list of objects with the following fields:

Property Type Description
date A date string in the format YYYY-MM-DD The date the data is relative to, depending on the group-type:
day - the specific day the data relates to.
week - the first day (Sunday) of the week the data relates to.
month - the first day of the month the data relates to.
followers_count Number Number of followers.

Retrieving a User’s Followers Statistics

GET /v2/users/USER-ID/statistics/followers

Authenticated: yes

This API returns a JSON object containing a user’s followers statistics, based on a certain interval and grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/1/statistics/followers?from=2017-02-01&to=2017-05-31&group=month"
{
    "response": {
        "statistics": [
            {
                "date": "2017-02-01",
                "followers_count": 443
            },
            {
                "date": "2017-03-01",
                "followers_count": 442
            },
            {
                "date": "2017-04-01",
                "followers_count": 441
            },
            {
                "date": "2017-05-01",
                "followers_count": 444
            }
        ]
    }
}

Sources Statistics

Endpoints

GET /v2/organizations/ORGANIZATION-ID/statistics/sources
GET /v2/users/USER-ID/statistics/sources
GET /v2/shows/SHOW-ID/statistics/sources
GET /v2/episodes/EPISODE-ID/statistics/sources

These endpoints also support CSV export.

Request Parameters

These are the request parameters for any Sources Statistics request.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
group Yes String The group-type to apply to the statistics. It can be day, week, or month.
precision Yes Number Precision, in decimal places, of the percentage returned for each source (defaults to 0).

Response

The Sources Statistics API always returns a JSON object with two proprieties, overall and details, each containing a list.

The overall list contains objects with the following properties:

Property Type Description
name String The name of the source.
plays_count Number Total number of plays and downloads from this source.
percentage Number Percentage of plays and downloads from this source.

The details list contains objects with the following properties:

Property Type Description
date A date string in the format YYYY-MM-DD The date the data is relative to, depending on the group-type:
day - the specific day the data relates to.
week - the first day (Sunday) of the week the data relates to.
month - the first day of the month the data relates to.
* Number Percentage of plays and downloads from each source on that time period. The property is the name of the source and the value will be the percentage. i.e. “YouTube”: 10 means that 10% of plays/downloads came from YouTube in that time frame.

Retrieving an Organization’s Sources Statistics

GET /v2/organizations/ORGANIZATION-ID/statistics/sources

Authenticated: yes

This API returns a JSON object containing the statistics relative to the play and download sources, grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/1/statistics/sources?from=2016-12-01&to=2016-12-07&group=day&precision=0"
{
    "response": {
        "statistics": {
            "overall": [
                {
                    "percentage": 30,
                    "plays_count": 15,
                    "name": "Spreaker, Website"
                },
                {
                    "percentage": 28,
                    "plays_count": 14,
                    "name": "YouTube"
                },
                {
                    "percentage": 16,
                    "plays_count": 8,
                    "name": "foo.com"
                },
                {
                    "percentage": 14,
                    "plays_count": 7,
                    "name": "iHeartRadio"
                },
                {
                    "percentage": 12,
                    "plays_count": 6,
                    "name": "Others"
                }
            ],
            "details": [
                {
                    "date": "2016-12-01",
                    "Spreaker, Website": 10,
                    "foo.com": 5,
                    "iHeartRadio": 1,
                    "YouTube": 2
                },
                {
                    "date": "2016-12-02",
                    "Spreaker, Website": 5,
                    "iHeartRadio": 1,
                    "YouTube": 2,
                    "Others": 1
                },
                {
                    "date": "2016-12-03",
                    "foo.com": 3,
                    "iHeartRadio": 1,
                    "YouTube": 2,
                    "Others": 1
                },
                {
                    "date": "2016-12-04",
                    "iHeartRadio": 1,
                    "YouTube": 2,
                    "Others": 2
                },
                {
                    "date": "2016-12-05",
                    "iHeartRadio": 1,
                    "YouTube": 2,
                    "Others": 2
                },
                {
                    "date": "2016-12-06",
                    "iHeartRadio": 1,
                    "YouTube": 2,
                    "Others": 1
                },
                {
                    "date": "2016-12-07",
                    "iHeartRadio": 1,
                    "YouTube": 2,
                    "Others": 1
                }
            ]
        }
    }
}

Retrieving a User’s Sources Statistics

This endpoint is deprecated and will be removed in a future release. Please use the organization, show or episode based endpoints instead. 

GET /v2/users/USER-ID/statistics/sources

Authenticated: yes

This API returns a JSON object containing the statistics relative to the play and download sources, grouped by the requested group-type. The response has the same shape as the organization example above.

Retrieving a Show’s Sources Statistics

GET /v2/shows/SHOW-ID/statistics/sources

Authenticated: yes

This API returns a JSON object containing the statistics relative to the play and download sources, grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/123/statistics/sources?from=2016-12-01&to=2016-12-05&group=week"

Returns the same JSON shape as the organization example above.

Retrieving an Episode’s Sources Statistics

GET /v2/episodes/EPISODE-ID/statistics/sources

Authenticated: yes

This API returns a JSON object containing the statistics relative to the plays and download sources, grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/321/statistics/sources?from=2016-12-01&to=2016-12-07&group=month"

Returns the same JSON shape as the organization example above.

Devices Statistics

Endpoints

GET /v2/organizations/ORGANIZATION-ID/statistics/devices
GET /v2/users/USER-ID/statistics/devices
GET /v2/shows/SHOW-ID/statistics/devices
GET /v2/episodes/EPISODE-ID/statistics/devices

These endpoints also support CSV export.

Request Parameters

These are the request parameters for Devices Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
precision Yes Number Precision, in decimal places, of the percentage returned for each device type (defaults to 0).

Response

The Devices Statistics API always returns a list of device types and their respective percentages of plays and downloads.

Property Type Description
name String The name of the type of device.
Can be Desktop, Mobile, Tablet, Others.
percentage Number Percentage of plays and downloads from this device type.

Retrieving an Organization’s Devices Statistics

GET /v2/organizations/ORGANIZATION-ID/statistics/devices

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/1/statistics/devices?from=2016-12-01&to=2016-12-07"
{
    "response": {
        "statistics": [
            {
                "name": "Desktop",
                "percentage": 59
            },
            {
                "name": "Mobile",
                "percentage": 34
            },
            {
                "name": "Tablet",
                "percentage": 5
            },
            {
                "name": "Others",
                "percentage": 2
            }
        ]
    }
}

Retrieving a User’s Devices Statistics

This endpoint is deprecated and will be removed in a future release. Please use the episode or show based endpoints instead. 

GET /v2/users/USER-ID/statistics/devices

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/1/statistics/devices?from=2016-12-01&to=2016-12-07"

Returns the same JSON shape as the organization example above.

Retrieving a Show’s Devices Statistics

GET /v2/shows/SHOW-ID/statistics/devices

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/123/statistics/devices?from=2016-12-01&to=2016-12-05&precision=2"

Returns the same JSON shape as the organization example above.

Retrieving an Episode’s Devices Statistics

GET /v2/episodes/EPISODE-ID/statistics/devices

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/321/statistics/devices?from=2016-12-01&to=2016-12-07"

Returns the same JSON shape as the organization example above.

Operating Systems Statistics

Endpoints

GET /v2/organizations/ORGANIZATION-ID/statistics/os
GET /v2/users/USER-ID/statistics/os
GET /v2/shows/SHOW-ID/statistics/os
GET /v2/episodes/EPISODE-ID/statistics/os

These endpoints also support CSV export.

Request Parameters

These are the request parameters for Operating Systems Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
precision Yes Number Precision, in decimal places, of the percentage returned for each device type (defaults to 0).

Response

The Operating Systems Statistics API always returns a JSON object with the proprieties desktop and mobile, each containing a list of its own following proprieties. The mobile list aggregates operating systems from both mobile and tablet devices.

Property Type Description
name String The name of the operating system.
percentage Number Percentage of plays and downloads from this operating system.

Retrieving an Organization’s Operating Systems Statistics

GET /v2/organizations/ORGANIZATION-ID/statistics/os

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/1/statistics/os?from=2016-12-01&to=2016-12-07"
{
    "response": {
        "statistics": {
            "desktop": [
                {
                    "name": "Windows",
                    "percentage": 67
                },
                {
                    "name": "MacOS",
                    "percentage": 33
                }
            ],
            "mobile": [
                {
                    "name": "iOS",
                    "percentage": 55
                },
                {
                    "name": "Android",
                    "percentage": 45
                }
            ]
        }
    }
}

Retrieving a User’s Operating Systems Statistics

This endpoint is deprecated and will be removed in a future release. Please use the episode or show based endpoints instead. 

GET /v2/users/USER-ID/statistics/os

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/1/statistics/os?from=2016-12-01&to=2016-12-07"

Returns the same JSON shape as the organization example above.

Retrieving a Show’s Operating Systems Statistics

GET /v2/shows/SHOW-ID/statistics/os

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/123/statistics/os?from=2016-12-01&to=2016-12-05&precision=2"

Returns the same JSON shape as the organization example above.

Retrieving an Episode’s Operating Systems Statistics

GET /v2/episodes/EPISODE-ID/statistics/os

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/321/statistics/os?from=2016-12-01&to=2016-12-07"

Returns the same JSON shape as the organization example above.

Geographic Statistics

Endpoints

GET /v2/organizations/ORGANIZATION-ID/statistics/geographics
GET /v2/users/USER-ID/statistics/geographics
GET /v2/shows/SHOW-ID/statistics/geographics

These endpoints also support CSV export.

Request Parameters

These are the request parameters for Geographic Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
precision Yes Number Precision, in decimal places, of the percentage returned for each country and city (defaults to 0).

Response

The Geographic Statistics API always returns a JSON object with two proprieties, country and city, that each contain a list. Each of the lists has objects with the following fields:

Property Type Description
name String The name of the place, either country or city.
percentage Number The percentage of plays and downloads from this place.

Retrieving an Organization’s Geographic Statistics

GET /v2/organizations/ORGANIZATION-ID/statistics/geographics

Authenticated: yes

This API returns a JSON object containing the statistics relative to the countries and cities from which an organization’s shows and episodes were listened in from, based on a certain interval and with the requested precision.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/organizations/1/statistics/geographics?from=2016-10-10&to=2016-10-12&precision=2"
{
    "response": {
        "statistics": {
            "country": [
                {
                    "name": "United States",
                    "percentage": 39.47
                },
                {
                    "name": "Italy",
                    "percentage": 23.68
                },
                {
                    "name": "Poland",
                    "percentage": 21.05
                },
                {
                    "name": "France",
                    "percentage": 7.89
                },
                {
                    "name": "Germany",
                    "percentage": 5.26
                },
                {
                    "name": "Spain",
                    "percentage": 2.63
                }
            ],
            "city": [
                {
                    "name": "Austin, TX, United States",
                    "percentage": 50
                },
                {
                    "name": "San Francisco, CA, United States",
                    "percentage": 25
                },
                {
                    "name": "Taranto, Italy",
                    "percentage": 25
                }
            ]
        }
    }
}

Retrieving a User’s Geographic Statistics

This endpoint is deprecated and will be removed in a future release. Please use the show based endpoint instead. 

GET /v2/users/USER-ID/statistics/geographics

Authenticated: yes

This API returns a JSON object containing the statistics relative to the countries and cities from which a user’s shows and episodes were listened in from, based on a certain interval and with the requested precision. The response has the same shape as the organization example above.

Retrieving a Show’s Geographic Statistics

GET /v2/shows/SHOW-ID/statistics/geographics

Authenticated: yes

This API returns a JSON object containing the statistics relative to the countries and cities from which a specific show was listened in from, based on a certain interval and with the requested precision.

Listeners Statistics

Request Parameters

These are the request parameters for Listeners Statistics.

Parameter Required Type Description
from Yes A date string in the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string in the format YYYY-MM-DD Date filter to get statistics until, and including, this date.
group Yes String The group-type to apply to the statistics. It can be day, week or month.

Response

The Listeners Statistics API always return a list of objects with the following fields:

Property Type Description
date A date string in the format YYYY-MM-DD The date the data is relative to, depending on the group-type:
day - the specific day the data relates to.
week - the first day (Sunday) of the week the data relates to.
month - the first day of the month the data relates to.
listeners_count Number Number of listeners.

This endpoint also supports CSV export.

Retrieving a Show’s Listeners Statistics

GET /v2/shows/SHOW-ID/statistics/listeners

Authenticated: yes

This API returns a JSON object containing statistics relative to all the listeners of a show, according to a particular interval and grouped by the requested group-type.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/1/statistics/listeners?from=2020-01-10&to=2020-01-12&group=day"
{
    "response": {
        "statistics": [
            {
                "date": "2020-01-10",
                "listeners_count": 123
            },
            {
                "date": "2020-01-11",
                "listeners_count": 456
            },
            {
                "date": "2020-01-12",
                "listeners_count": 789
            }
        ]
    }
}