Popularity

The popularity APIs return the total listen and listeners count for various entities and also a way to query top entities for a given artist.

GET /1/popularity/top-recordings-for-artist/(artist_mbid)

Get the top recordings by listen count for a given artist. The response is of the following format:

[
  {
    "artist_mbids": [
      "b7ffd2af-418f-4be2-bdd1-22f8b48613da"
    ],
    "artist_name": "Nine Inch Nails",
    "caa_id": 2546761764,
    "caa_release_mbid": "2d410836-5add-3661-b0b0-168ba1696611",
    "length": 373133,
    "recording_mbid": "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
    "recording_name": "Closer",
    "release_color": {
        "blue": 104,
        "green": 104,
        "red": 84
    },
    "release_mbid": "ba8701ba-dc7c-4bca-9c83-846ee8c3d576",
    "release_name": "The Downward Spiral",
    "total_listen_count": 1380798,
    "total_user_count": 129454
  }
]
Status Codes:
GET /1/popularity/top-release-groups-for-artist/(artist_mbid)

Get the top release groups by listen count for a given artist. The response is of the following format:

[
  {
    "artist": {
      "artist_credit_id": 368737,
      "artists": [],
      "name": "Pritam"
    },
    "release": {
      "caa_id": 14996821464,
      "caa_release_mbid": "488ef20e-7a2b-4daf-8bee-4f54fe26c7ab",
      "date": "2016-10-26",
      "name": "Ae Dil Hai Mushkil",
      "rels": [],
      "type": "Album"
    },
    "release_color": {
      "blue": 64,
      "green": 69,
      "red": 113
    },
    "release_group": {
      "caa_id": 14996821464,
      "caa_release_mbid": "488ef20e-7a2b-4daf-8bee-4f54fe26c7ab",
      "date": "2016-10-26",
      "name": "Ae Dil Hai Mushkil",
      "rels": [],
      "type": "Album"
    },
    "release_group_mbid": "d0991cc9-2277-4f5e-bd4d-2fa44507f623",
    "tag": {},
    "total_listen_count": 1432,
    "total_user_count": 82
  },
]
Parameters:
  • artist_mbid (str) – the mbid of the artist to get top release groups for

Status Codes:
POST /1/popularity/recording

Get the total listen count and total unique listeners count for a given recording.

A JSON document with a list of recording_mbids and inc string must be POSTed. Up to MAX_ITEMS_PER_GET items can be requested at once. Example:

{
    "recording_mbids": [
        "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "22ad712e-ce73-9f0c-4e97-9f0e53144411"
    ]
}

The response maintains the order of the recording mbids supplied and also includes any recordings for which the data was not found with counts set to null. Example:

[
    {
        "recording_mbid": "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "total_listen_count": 1000,
        "total_user_count": 10
    },
    {
        "recording_mbid": "22ad712e-ce73-9f0c-4e97-9f0e53144411",
        "total_listen_count": null,
        "total_user_count": null
    }
]
Status Codes:
POST /1/popularity/artist

Get the total listen count and total unique listeners count for a given artist.

A JSON document with a list of artists and inc string must be POSTed. Up to MAX_ITEMS_PER_GET items can be requested at once. Example:

{
    "artist_mbids": [
        "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "22ad712e-ce73-9f0c-4e97-9f0e53144411"
    ]
}

The response maintains the order of the artist mbids supplied and also includes any artists for which the data was not found with counts set to null. Example:

[
    {
        "artist_mbid": "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "total_listen_count": 1000,
        "total_user_count": 10
    },
    {
        "artist_mbid": "22ad712e-ce73-9f0c-4e97-9f0e53144411",
        "total_listen_count": null,
        "total_user_count": null
    }
]
Status Codes:
POST /1/popularity/release

Get the total listen count and total unique listeners count for a given release.

A JSON document with a list of releases and inc string must be POSTed. Up to MAX_ITEMS_PER_GET items can be requested at once. Example:

{
    "release_mbids": [
        "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "22ad712e-ce73-9f0c-4e97-9f0e53144411"
    ]
}

The response maintains the order of the release mbids supplied and also includes any releases for which the data was not found with counts set to null. Example:

[
    {
        "release_mbid": "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "total_listen_count": 1000,
        "total_user_count": 10
    },
    {
        "release_mbid": "22ad712e-ce73-9f0c-4e97-9f0e53144411",
        "total_listen_count": null,
        "total_user_count": null
    }
]
Status Codes:
POST /1/popularity/release-group

Get the total listen count and total unique listeners count for a given release group.

A JSON document with a list of release groups and inc string must be POSTed. Up to MAX_ITEMS_PER_GET items can be requested at once. Example:

{
    "release_group_mbids": [
        "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "22ad712e-ce73-9f0c-4e97-9f0e53144411"
    ]
}

The response maintains the order of the release group mbids supplied and also includes any release groups for which the data was not found with counts set to null. Example:

[
    {
        "release_group_mbid": "13dd61c7-ce73-4e97-9f0c-9f0e53144411",
        "total_listen_count": 1000,
        "total_user_count": 10
    },
    {
        "release_group_mbid": "22ad712e-ce73-9f0c-4e97-9f0e53144411",
        "total_listen_count": null,
        "total_user_count": null
    }
]
Status Codes: