Get Track Stats by Platform

​

Return historical stats for a track on a platform. mode selects the aggregation bucket. platform accepts chartmetric, spotify, youtube, tiktok, etc. type query param selects the stat column (e.g. streams, popularity). Wrapped in a single-element array under obj.

Path Parameters
  • platform
    Type: string enum
    required

    Streaming platform whose stats to retrieve. One of shazam, spotify, youtube, tiktok, genius, soundcloud, chartmetric, line, melon, radio.

    values
    • shazam
    • spotify
    • youtube
    • tiktok
    • genius
  • id
    required

    Track identifier. By default a Chartmetric track ID; if isDomainId=true, a platform-native ID (numeric for shazam/genius, string for others).

    • Track identifier. By default a Chartmetric track ID; if isDomainId=true, a platform-native ID (numeric for shazam/genius, string for others).

      • Type: integer

        Track identifier. By default a Chartmetric track ID; if isDomainId=true, a platform-native ID (numeric for shazam/genius, string for others).

  • mode
    Type: string enum
    required

    Selection algorithm when multiple platform tracks map to one Chartmetric track. highest-playcounts picks the most-played; most-history picks the longest-tracked.

    values
    • highest-playcounts
    • most-history
Query Parameters
  • since
    Type: string Format: date

    Inclusive start of the stat date range in YYYY-MM-DD format. Defaults to 180 days before today.

  • type

    Stat column to retrieve; allowed values depend on platform (e.g. spotify → streams/popularity; tiktok → posts/views/sound_*). Each platform has a default.

    • enum
      const:  
      total_spins

      Stat column to retrieve; allowed values depend on platform (e.g. spotify → streams/popularity; tiktok → posts/views/sound_*). Each platform has a default.

      values
      • total_spins
  • until
    Type: string Format: date

    Inclusive end of the stat date range in YYYY-MM-DD format. Defaults to today.

  • latest
    Type: boolean

    If true, return only the most recent data point regardless of since/until.

  • interpolated
    Type: boolean

    If true, fill gaps in the time series with interpolated values to produce a smooth curve. Not applicable for Spotify.

  • isDomainId
    Type: boolean

    If true, treat id as a platform-native ID rather than a Chartmetric track ID. Defaults to false.

  • extrapolated
    Type: string enum

    Extrapolation mode for projecting values outside the observed range. One of before, after, both.

    values
    • before
    • after
    • both
Responses
  • application/json
Request Example for get/api/track/{id}/{platform}/stats/{mode}
curl https://api.chartmetric.com/api/track/1/shazam/stats/highest-playcounts \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "obj": [
    {
      "domain": "spotify",
      "track_domain_id": "55n9yjI6qqXh5F2mYvUc2y",
      "type": "streams",
      "data": [
        {
          "value": 80,
          "timestp": "2022-01-01T00:00:00.000Z"
        },
        {
          "value": 80,
          "timestp": "2022-01-02T00:00:00.000Z"
        }
      ]
    }
  ]
}

Success