Total Airplays by Entity

​

Returns airplay counts for the given :type (artist, album, track), grouped by the requested :entity (country, city, station, track). Each item includes a plays_trend time series.

Path Parameters
  • id
    Type: integer
    min:  
    0
    max:  
    2147483647
    required

    Chartmetric ID for the entity in :type (artist / album / track ID).

  • type
    Type: string enum
    required

    Entity kind that :id refers to (one of artist | album | track).

    values
    • artist
    • track
    • album
  • entity
    Type: string enum
    required

    Grouping dimension for airplay totals (one of country | city | station | track).

    values
    • country
    • city
    • station
    • track
Query Parameters
  • since
    Type: string Format: date
    required

    Start date for aggregating airplay totals in ISO format (e.g. 2025-11-01); defaults to 180 days ago.

  • station
    Type: integer
    min:  
    0
    max:  
    2147483647

    Chartmetric radio station ID; when set, restricts play counts to a single station.

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Maximum entries returned in the :entity grouping.

  • dateFormat
    Type: string enum

    Format of air_date in plays_trend items: ISO for ISO 8601 strings, UNIX for UTC epoch seconds.

    values
    • ISO
    • UNIX
Responses
  • application/json
Request Example for get/api/radio/{type}/{id}/airplay-totals/{entity}
curl 'https://api.chartmetric.com/api/radio/artist/0/airplay-totals/country?since=2026-01-21' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "obj": [
    {
      "code2": "US",
      "name": "United States",
      "plays": 81275,
      "plays_percent": 0.43441659094553425,
      "plays_trend": [
        {
          "air_date": "2023-01-01",
          "count": 916
        }
      ]
    }
  ]
}

Success