API: Statistics

In this page

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.

Overall Statistics

Endpoints

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 users, shows, and episodes statistics.
downloads_count Number The number of all-time downloads.
Available in users, shows, and episodes statistics.
plays_ondemand_count Number The number of all-time on demand plays.
Available in users, shows, and episodes statistics.
plays_live_count Number The number of all-time live plays.
Available in 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.
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 a User’s Overall Statistics

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/users/USER-ID/statistics/plays
GET /v2/shows/SHOW-ID/statistics/plays
GET /v2/episodes/EPISODE-ID/statistics/plays

CSV File

In order to get a CSV file with the Play Statistics, a .csv needs to be added to the end of the endpoint and then use the same parameters as the regular request.

GET /v2/users/USER-ID/statistics/plays.csv
GET /v2/shows/SHOW-ID/statistics/plays.csv
GET /v2/episodes/EPISODE-ID/statistics/plays.csv

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 a User’s Play Statistics

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.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/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 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"
{
    "response": {
        "statistics": [
            {
                "date": "2016-10-08",
                "plays_count": 25,
                "plays_live_count": 6,
                "plays_ondemand_count": 19,
                "downloads_count": 24
            },
            {
                "date": "2016-10-15",
                "plays_count": 4,
                "plays_live_count": 1,
                "plays_ondemand_count": 3,
                "downloads_count": 7
            }
        ]
    }
}

Retrieving a User’s Shows’ Total Play Statistics

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.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/8114541/shows/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/users/8114541/shows/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=0&limit=3",
    "next_url": "https://api.spreaker.com/v2/users/8114541/shows/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=6&limit=3"
  }
}

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"
{
    "response": {
        "statistics": [
            {
                "date": "2016-10-01",
                "plays_count": 40,
                "plays_live_count": 16,
                "plays_ondemand_count": 14,
                "downloads_count": 27
            },
            {
                "date": "2016-11-01",
                "plays_count": 8,
                "plays_live_count": 3,
                "plays_ondemand_count": 5,
                "downloads_count": 9
            }
        ]
    }
}

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"

The response body is a paginated list of items.

{
  "response": {
    "items": [
      {
        "episode_id": 7869337,
        "title": "SLS48: Christian Radio Syndication and Podcasting, Matt Thomas of Know The Truth (KTT.org)",
        "is_deleted": false,
        "is_transferred": false,
        "plays_count": 38,
        "plays_live_count": 0,
        "plays_ondemand_count": 38,
        "downloads_count": 30
      },
      {
        "episode_id": 7869150,
        "title": "SLS47: Christian Radio to Podcasting, Wayne Shepherd, Radio/Podcast Host",
        "is_deleted": false,
        "is_transferred": false,
        "plays_count": 0,
        "plays_live_count": 0,
        "plays_ondemand_count": 0,
        "downloads_count": 39
      },
      {
        "episode_id": 7811083,
        "title": "SLS46: Faith-Based Podcasting, Dr. Jerry Johnson, CEO of National Religious Broadcasters",
        "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/shows/1433865/episodes/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=0&limit=3",
    "next_url": "https://api.spreaker.com/v2/shows/1433865/episodes/statistics/plays/totals?from=2016-10-10&to=2016-10-12&offset=6&limit=3"
  }
}

Likes Statistics

Endpoints

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

CSV File

In order to get a CSV file of the Likes Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

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

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

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

CSV File

In order to get a CSV file of the Followers Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

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

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/users/USER-ID/statistics/sources
GET /v2/shows/SHOW-ID/statistics/sources
GET /v2/episodes/EPISODE-ID/statistics/sources

CSV File

In order to get a CSV file with the Sources Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

GET /v2/users/USER-ID/statistics/sources.csv
GET /v2/shows/SHOW-ID/statistics/sources.csv
GET /v2/episodes/EPISODE-ID/statistics/sources.csv

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 a User’s Sources Statistics

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.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/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 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"
{
    "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-11-27",
                    "Spreaker, Website": 10,
                    "foo.com": 5,
                    "iHeartRadio": 6,
                    "YouTube": 2,
                    "Others": 3
                },
                {
                    "date": "2016-12-04",
                    "Spreaker, Website": 5,
                    "iHeartRadio": 1,
                    "YouTube": 12,
                    "foo.com": 3,
                    "Others": 3
                }
            ]
        }
    }
}

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"
{
    "response": {
        "statistics": {
            "overall": [
                {
                    "percentage": 30,
                    "plays_count": 15,
                    "name": "Spreaker, Website"
                },
                {
                    "percentage": 28,
                    "plays_count": 14,
                    "name": "YouTube"
                },
                {
                    "percentage": 14,
                    "plays_count": 7,
                    "name": "iHeartRadio"
                },
                {
                    "percentage": 16,
                    "plays_count": 8,
                    "name": "foo.com"
                },
                {
                    "percentage": 12,
                    "plays_count": 6,
                    "name": "Others"
                }
            ],
            "details": [
                {
                    "date": "2016-12-01",
                    "Spreaker, Website": 15,
                    "YouTube": 14,
                    "iHeartRadio": 7,
                    "foo.com": 8,
                    "Others": 6
                }
            ]
        }
    }
}

Devices Statistics

Endpoints

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

CSV File

In order to get a CSV file with Devices Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

GET /v2/users/USER-ID/statistics/devices.csv
GET /v2/shows/SHOW-ID/statistics/devices.csv
GET /v2/episodes/EPISODE-ID/statistics/devices.csv

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 a User’s Devices Statistics

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"
{
    "response": {
        "statistics": [
            {
                "name": "Desktop",
                "percentage": 59
            },
            {
                "name": "Mobile",
                "percentage": 34
            },
            {
                "name": "Tablet",
                "percentage": 5
            },
            {
                "name": "Others",
                "percentage": 2
            }
        ]
    }
}

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"
{
    "response": {
        "statistics": [
            {
                "name": "Desktop",
                "percentage": 44.67
            },
            {
                "name": "Mobile",
                "percentage": 37.08
            },
            {
                "name": "Tablet",
                "percentage": 10.33
            },
            {
                "name": "Others",
                "percentage": 7.92
            }
        ]
    }
}

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"
{
    "response": {
        "statistics": [
            {
                "name": "Mobile",
                "percentage": 75
            },
            {
                "name": "Desktop",
                "percentage": 12
            },
            {
                "name": "Tablet",
                "percentage": 8
            },
            {
                "name": "Others",
                "percentage": 5
            }
        ]
    }
}

Operating Systems Statistics

Endpoints

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

CSV File

In order to get a CSV file with the Operating Systems Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

GET /v2/users/USER-ID/statistics/os.csv
GET /v2/shows/SHOW-ID/statistics/os.csv
GET /v2/episodes/EPISODE-ID/statistics/os.csv

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 a User’s Operating Systems Statistics

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"
{
    "response": {
        "statistics": {
            "desktop": [
                {
                    "name": "Windows",
                    "percentage": 67
                },
                {
                    "name": "MacOS",
                    "percentage": 33
                }
            ],
            "mobile": [
                {
                    "name": "iOS",
                    "percentage": 55
                },
                {
                    "name": "Android",
                    "percentage": 45
                }
            ]
        }
    }
}

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"
{
    "response": {
        "statistics": {
            "desktop": [
                {
                    "name": "Windows",
                    "percentage": 63.5
                },
                {
                    "name": "MacOS",
                    "percentage": 32.5
                },
                {
                    "name": "Linux",
                    "percentage": 5
                }
            ],
            "mobile": [
                {
                    "name": "Android",
                    "percentage": 48.25
                },
                {
                    "name": "iOS",
                    "percentage": 42.5
                },
                {
                    "name": "Blackberry",
                    "percentage": 10.25
                }
            ]
        }
    }
}

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"
{
    "response": {
        "statistics": {
            "desktop": [
                {
                    "name": "Windows",
                    "percentage": 45
                },
                {
                    "name": "MacOS",
                    "percentage": 30
                },
                {
                    "name": "Linux",
                    "percentage": 25
                }
            ],
            "mobile": [
                {
                    "name": "iOS",
                    "percentage": 79
                },
                {
                    "name": "Android",
                    "percentage": 21
                }
            ]
        }
    }
}

Geographic Statistics

Endpoints

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

CSV File

In order to get a CSV file with the Geographic Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

GET /v2/users/USER-ID/statistics/geographics.csv
GET /v2/shows/SHOW-ID/statistics/geographics.csv

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 a User’s Geographic Statistics

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.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/users/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 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

Endpoints

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

CSV File

In order to get a CSV file of the Listeners Statistics, a .csv needs to be added to the end of the endpoint and then used with the same parameters as the regular request.

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

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.

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
            }
        ]
    }
}