Statistics

ListenBrainz has a statistics infrastructure that collects and computes statistics from the listen data that has been stored in the database. The endpoints in this section offer a way to get this data programmatically.

GET /1/stats/sitewide/listening-activity

Get the listening activity for entire site. The listening activity shows the number of listens the user has submitted over a period of time.

A sample response from the endpoint may look like:

{
    "payload": {
        "from_ts": 1587945600,
        "last_updated": 1592807084,
        "listening_activity": [
            {
                "from_ts": 1587945600,
                "listen_count": 26,
                "time_range": "Monday 27 April 2020",
                "to_ts": 1588031999
            },
            {
                "from_ts": 1588032000,
                "listen_count": 57,
                "time_range": "Tuesday 28 April 2020",
                "to_ts": 1588118399
            },
            {
                "from_ts": 1588118400,
                "listen_count": 33,
                "time_range": "Wednesday 29 April 2020",
                "to_ts": 1588204799
            }
        ],
        "to_ts": 1589155200,
        "range": "week"
    }
}

Note

  • This endpoint is currently in beta
  • The example above shows the data for three days only, however we calculate the statistics for the current time range and the previous time range. For example for weekly statistics the data is calculated for the current as well as the past week.
Parameters:
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
Response Headers:
 
GET /1/stats/sitewide/recordings

Get sitewide top recordings.

A sample response from the endpoint may look like:

{
    "payload": {
        "recordings": [
            {
                "artist_mbids": [],
                "artist_name": "Ellie Goulding",
                "listen_count": 25,
                "recording_mbid": "0fe11cd3-0be4-467b-84fa-0bd524d45d74",
                "release_mbid": "",
                "release_name": "Delirium (Deluxe)",
                "track_name": "Love Me Like You Do - From \"Fifty Shades of Grey\""
            },
            {
                "artist_mbids": [],
                "artist_name": "The Fray",
                "listen_count": 23,
                "recording_mbid": "0008ab49-a6ad-40b5-aa90-9d2779265c22",
                "release_mbid": "",
                "release_name": "How to Save a Life",
                "track_name": "How to Save a Life"
            }
        ],
        "offset": 0,
        "count": 2,
        "range": "year",
        "last_updated": 1588494361,
        "from_ts": 1009823400,
        "to_ts": 1590029157
    }
}

Note

  • This endpoint is currently in beta
  • We only calculate the top 1000 all_time recordings
  • artist_mbids, artist_msid, release_name, release_mbid, release_msid, recording_mbid and recording_msid are optional fields and may not be present in all the responses
Parameters:
  • count (int) – Optional, number of artists to return for each time range, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET
  • offset (int) – Optional, number of artists to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 artists will be skipped, defaults to 0
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
Response Headers:
 
GET /1/stats/sitewide/artist-map

Get the sitewide artist map. The artist map shows the number of artists listened to by users from different countries of the world.

A sample response from the endpoint may look like:

{
    "payload": {
        "from_ts": 1587945600,
        "last_updated": 1592807084,
        "artist_map": [
            {
                "country": "USA",
                "artist_count": 34
            },
            {
                "country": "GBR",
                "artist_count": 69
            },
            {
                "country": "IND",
                "artist_count": 32
            }
        ],
        "stats_range": "all_time"
        "to_ts": 1589155200,
    }
}

Note

  • This endpoint is currently in beta
  • We cache the results for this query for a week to improve page load times, if you want to request fresh data
you can use the force_recalculate flag.
Parameters:
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
  • force_recalculate (bool) – Optional, recalculate the data instead of returning the cached result.
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 
GET /1/stats/sitewide/releases

Get sitewide top releases.

A sample response from the endpoint may look like:

{
    "payload": {
        "releases": [
            {
                "artist_mbids": [],
                "artist_name": "Coldplay",
                "listen_count": 26,
                "release_mbid": "",
                "release_name": "Live in Buenos Aires"
            },
            {
                "artist_mbids": [],
                "artist_name": "Ellie Goulding",
                "listen_count": 25,
                "release_mbid": "",
                "release_name": "Delirium (Deluxe)"
            },
            {
                "artist_mbids": [],
                "artist_name": "The Fray",
                "listen_count": 25,
                "release_mbid": "",
                "release_name": "How to Save a Life"
            },
        ],
        "offset": 0,
        "count": 2,
        "range": "year",
        "last_updated": 1588494361,
        "from_ts": 1009823400,
        "to_ts": 1590029157
    }
}

Note

  • This endpoint is currently in beta
  • artist_mbids, artist_msid, release_mbid and release_msid are optional fields and may not be present in all the responses
Parameters:
  • count (int) – Optional, number of artists to return for each time range, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET
  • offset (int) – Optional, number of artists to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 artists will be skipped, defaults to 0
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
Response Headers:
 
GET /1/stats/sitewide/artists

Get sitewide top artists.

A sample response from the endpoint may look like:

{
    "payload": {
        "artists": [
            {
                "artist_mbids": [],
                "artist_name": "Kanye West",
                "listen_count": 1305
            },
            {
                "artist_mbids": ["0b30341b-b59d-4979-8130-b66c0e475321"],
                "artist_name": "Lil Nas X",
                "listen_count": 1267
            }
        ],
        "offset": 0,
        "count": 2,
        "range": "year",
        "last_updated": 1588494361,
        "from_ts": 1009823400,
        "to_ts": 1590029157
    }
}

Note

  • This endpoint is currently in beta
  • artist_mbids and artist_msid are optional fields and may not be present in all the entries
  • We only calculate the top 1000 artists for each time period.
Parameters:
  • count (int) – Optional, number of artists to return for each time range, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET
  • offset (int) – Optional, number of artists to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 artists will be skipped, defaults to 0
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
Response Headers:
 
GET /1/stats/user/(user_name)/listening-activity

Get the listening activity for user user_name. The listening activity shows the number of listens the user has submitted over a period of time.

A sample response from the endpoint may look like:

{
    "payload": {
        "from_ts": 1587945600,
        "last_updated": 1592807084,
        "listening_activity": [
            {
                "from_ts": 1587945600,
                "listen_count": 26,
                "time_range": "Monday 27 April 2020",
                "to_ts": 1588031999
            },
            {
                "from_ts": 1588032000,
                "listen_count": 57,
                "time_range": "Tuesday 28 April 2020",
                "to_ts": 1588118399
            },
            {
                "from_ts": 1588118400,
                "listen_count": 33,
                "time_range": "Wednesday 29 April 2020",
                "to_ts": 1588204799
            },
        "to_ts": 1589155200,
        "user_id": "ishaanshah"
    }
}

Note

  • This endpoint is currently in beta
  • The example above shows the data for three days only, however we calculate the statistics for the current time range and the previous time range. For example for weekly statistics the data is calculated for the current as well as the past week.
  • For all_time listening activity statistics we only return the years which have more than zero listens.
Parameters:
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 
GET /1/stats/user/(user_name)/daily-activity

Get the daily activity for user user_name. The daily activity shows the number of listens submitted by the user for each hour of the day over a period of time. We assume that all listens are in UTC.

A sample response from the endpoint may look like:

{
    "payload": {
        "from_ts": 1587945600,
        "last_updated": 1592807084,
        "daily_activity": {
            "Monday": [
                {
                    "hour": 0
                    "listen_count": 26,
                },
                {
                    "hour": 1
                    "listen_count": 30,
                },
                {
                    "hour": 2
                    "listen_count": 4,
                },
                "..."
            ],
            "Tuesday": ["..."],
            "..."
        },
        "stats_range": "all_time",
        "to_ts": 1589155200,
        "user_id": "ishaanshah"
    }
}

Note

  • This endpoint is currently in beta
Parameters:
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 
GET /1/stats/user/(user_name)/year-in-music/

Get data for year in music stuff

GET /1/stats/user/(user_name)/recordings

Get top recordings for user user_name.

A sample response from the endpoint may look like:

{
    "payload": {
        "recordings": [
            {
                "artist_mbids": [],
                "artist_name": "Ellie Goulding",
                "listen_count": 25,
                "recording_mbid": "0fe11cd3-0be4-467b-84fa-0bd524d45d74",
                "release_mbid": "",
                "release_name": "Delirium (Deluxe)",
                "track_name": "Love Me Like You Do - From \"Fifty Shades of Grey\""
            },
            {
                "artist_mbids": [],
                "artist_name": "The Fray",
                "listen_count": 23,
                "recording_mbid": "0008ab49-a6ad-40b5-aa90-9d2779265c22",
                "release_mbid": "",
                "release_name": "How to Save a Life",
                "track_name": "How to Save a Life"
            }
        ],
        "count": 2,
        "total_recording_count": 175,
        "range": "all_time",
        "last_updated": 1588494361,
        "user_id": "John Doe",
        "from_ts": 1009823400,
        "to_ts": 1590029157
    }
}

Note

  • This endpoint is currently in beta
  • We only calculate the top 1000 all_time recordings
  • artist_mbids, artist_msid, release_name, release_mbid, release_msid, recording_mbid and recording_msid are optional fields and may not be present in all the responses
Parameters:
  • count (int) – Optional, number of recordings to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET
  • offset (int) – Optional, number of recordings to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 recordings will be skipped, defaults to 0
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 
GET /1/stats/user/(user_name)/artist-map

Get the artist map for user user_name. The artist map shows the number of artists the user has listened to from different countries of the world.

A sample response from the endpoint may look like:

{
    "payload": {
        "from_ts": 1587945600,
        "last_updated": 1592807084,
        "artist_map": [
            {
                "country": "USA",
                "artist_count": 34
            },
            {
                "country": "GBR",
                "artist_count": 69
            },
            {
                "country": "IND",
                "artist_count": 32
            }
        ],
        "stats_range": "all_time"
        "to_ts": 1589155200,
        "user_id": "ishaanshah"
    }
}

Note

  • This endpoint is currently in beta
  • We cache the results for this query for a week to improve page load times, if you want to request fresh data you can use the force_recalculate flag.
Parameters:
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
  • force_recalculate (bool) – Optional, recalculate the data instead of returning the cached result.
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 
GET /1/stats/user/(user_name)/releases

Get top releases for user user_name.

A sample response from the endpoint may look like:

{
    "payload": {
        "releases": [
            {
                "artist_mbids": [],
                "artist_name": "Coldplay",
                "listen_count": 26,
                "release_mbid": "",
                "release_name": "Live in Buenos Aires"
            },
            {
                "artist_mbids": [],
                "artist_name": "Ellie Goulding",
                "listen_count": 25,
                "release_mbid": "",
                "release_name": "Delirium (Deluxe)"
            },
            {
                "artist_mbids": [],
                "artist_name": "The Fray",
                "listen_count": 25,
                "release_mbid": "",
                "release_name": "How to Save a Life"
            },
        ],
        "count": 3,
        "total_release_count": 175,
        "range": "all_time",
        "last_updated": 1588494361,
        "user_id": "John Doe",
        "from_ts": 1009823400,
        "to_ts": 1590029157
    }
}

Note

  • This endpoint is currently in beta
  • artist_mbids, artist_msid, release_mbid and release_msid are optional fields and may not be present in all the responses
Parameters:
  • count (int) – Optional, number of releases to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET
  • offset (int) – Optional, number of releases to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 releases will be skipped, defaults to 0
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 
GET /1/stats/user/(user_name)/artists

Get top artists for user user_name.

A sample response from the endpoint may look like:

{
    "payload": {
        "artists": [
            {
               "artist_mbids": ["93e6118e-7fa8-49f6-9e02-699a1ebce105"],
               "artist_name": "The Local train",
               "listen_count": 385
            },
            {
               "artist_mbids": ["ae9ed5e2-4caf-4b3d-9cb3-2ad626b91714"],
               "artist_name": "Lenka",
               "listen_count": 333
            },
            {
               "artist_mbids": ["cc197bad-dc9c-440d-a5b5-d52ba2e14234"],
               "artist_name": "Coldplay",
               "listen_count": 321
            }
        ],
        "count": 3,
        "total_artist_count": 175,
        "range": "all_time",
        "last_updated": 1588494361,
        "user_id": "John Doe",
        "from_ts": 1009823400,
        "to_ts": 1590029157
    }
}

Note

  • This endpoint is currently in beta
  • artist_mbids and artist_msid are optional fields and may not be present in all the responses
Parameters:
  • count (int) – Optional, number of artists to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET
  • offset (int) – Optional, number of artists to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 artists will be skipped, defaults to 0
  • range (str) – Optional, time interval for which statistics should be returned, possible values are ALLOWED_STATISTICS_RANGE, defaults to all_time
Status Codes:
  • 200 OK – Successful query, you have data!
  • 204 No Content – Statistics for the user haven’t been calculated, empty response will be returned
  • 400 Bad Request – Bad request, check response['error'] for more details
  • 404 Not Found – User not found
Response Headers:
 

Constants

Constants that are relevant to using the API:

data.model.common_stat.ALLOWED_STATISTICS_RANGE = ['week', 'month', 'quarter', 'half_yearly', 'year', 'all_time', 'this_week', 'this_month', 'this_year']

list of allowed value for range param accepted by various statistics endpoints