Interested in working with us? We offer a superb REMOTE work opportunity for a DEVOP.

Click here to find out more.

API: Statistics

In this page

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.
Available in users, shows, and episodes statistics.
downloads_count Number The number of all-time downloads.
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,
            "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,
            "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,
            "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
                }
            }
        }
    }
}

Play Statistics

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

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.

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.

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"
{
    "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.
image_url String The image of a country’s flag (only available for countries).

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,
                    "image_url": "https://www.test-spreaker.com/images/flags_90x60/us.png"
                },
                {
                    "name": "Italy",
                    "percentage": 23.68,
                    "image_url": "https://www.test-spreaker.com/images/flags_90x60/it.png"
                },
                {
                    "name": "Poland",
                    "percentage": 21.05,
                    "image_url": "https://www.test-spreaker.com/images/flags_90x60/pl.png"
                },
                {
                    "name": "France",
                    "percentage": 7.89,
                    "image_url": "https://www.test-spreaker.com/images/flags_90x60/fr.png"
                },
                {
                    "name": "Germany",
                    "percentage": 5.26,
                    "image_url": "https://www.test-spreaker.com/images/flags_90x60/de.png"
                },
                {
                    "name": "Spain",
                    "percentage": 2.63,
                    "image_url": "https://www.test-spreaker.com/images/flags_90x60/es.png"
                }
            ],
            "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.

Demographic Statistics

Endpoints

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

CSV File

In order to get a CSV file with the Demographic 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/demographics.csv
GET /v2/shows/SHOW-ID/statistics/demographics.csv

Request Parameters

These are the request parameters for Demographic Statistics.

Parameter Required Type Description
from Yes A date string with the format YYYY-MM-DD Date filter to get statistics since, and including, this date.
to Yes A date string with 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 Demographic Statistics API always return a list of objects with the following fields:

Property Type Description
range String The age range of the related object.
males_percentage Number Percentage of plays and downloads by males on this age range.
females_percentage Number Percentage of plays and downloads by females on this age range.

Retrieving a User’s Demographic Statistics

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

Authenticated: yes

This API returns a JSON object containing all of a user’s show and episode demographics statistics, 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/demographics?from=2016-10-10&to=2016-10-12&precision=2"
{
    "response": {
        "statistics": [
            {
                "range": "13-17",
                "males_percentage": 10.42,
                "females_percentage": 22.92
            },
            {
                "range": "18-24",
                "males_percentage": 2.08,
                "females_percentage": 14.58
            },
            {
                "range": "25-34",
                "males_percentage": 8.33,
                "females_percentage": 0
            },
            {
                "range": "35-44",
                "males_percentage": 0,
                "females_percentage": 16.67
            },
            {
                "range": "45-54",
                "males_percentage": 4.17,
                "females_percentage": 0
            },
            {
                "range": "55+",
                "males_percentage": 8.33,
                "females_percentage": 12.5
            }
        ]
    }
}

Retrieving a Show’s Demographic Statistics

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

Authenticated: yes

This API returns a JSON object containing a specific show’s demogrpahics statistics, based on a certain interval and with the requested precision.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/shows/123/statistics/demographics?from=2016-10-10&to=2016-10-12&precision=2"
{
    "response": {
        "statistics": [
            {
                "range": "13-17",
                "males_percentage": 10.42,
                "females_percentage": 12.92
            },
            {
                "range": "18-24",
                "males_percentage": 2.08,
                "females_percentage": 7.58
            },
            {
                "range": "25-34",
                "males_percentage": 8.33,
                "females_percentage": 0
            },
            {
                "range": "35-44",
                "males_percentage": 0,
                "females_percentage": 16.67
            },
            {
                "range": "45-54",
                "males_percentage": 4.17,
                "females_percentage": 0
            },
            {
                "range": "55+",
                "males_percentage": 18.33,
                "females_percentage": 19.5
            }
        ]
    }
}