---
title: "Get Spotify Fresh Finds Charts"
method: GET
path: "/api/charts/spotify/freshfind"
tags: ["Charts"]
---

# Get Spotify Fresh Finds Charts

`GET /api/charts/spotify/freshfind`

## Request

- Base URL: `https://api.chartmetric.com`
- URL: `https://api.chartmetric.com/api/charts/spotify/freshfind`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/docs/api/charts/spotify/freshfind/get.ts> (a function with typed inputs; its response is checked against the schema)

Return tracks from the Spotify Fresh Finds charts for a given date. Useful for spotting new independent-artist material. Unlike the other Spotify endpoints, the response is a bare array under `obj` (the handler does NOT wrap in `{ length, data }`).

## Query parameters

- `date` string, date-time: Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`.
- `latest` boolean: If true, use the most recently available date and ignore `date`.
- `limit` integer: Maximum number of items to return per request.
- `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate.

## Response `200`

Success

- object
  - `obj` object[], required: List of Fresh Finds chart rows.
    - `spotify_track_id` string, nullable: Spotify track ID.
    - `rank` integer, nullable: Position in the Fresh Finds chart (1 = top).
    - `num_all_playlists` integer, nullable: Total Spotify playlists currently containing this track.
    - `num_ff_playlists` integer, nullable: Number of Fresh Finds playlists containing this track.
    - `fresh_finds_playlists_ids` integer[], nullable: Chartmetric playlist IDs of Fresh Finds playlists containing this track.
    - `fresh_finds_playlists` string[], nullable: Names of Fresh Finds playlists containing this track.
    - `artists` union: Artist info for the track. May be a single object or an array depending on whether the track has multiple artists.
      - object
        - `id` integer, nullable: Chartmetric artist ID.
        - `name` string, nullable: Artist name.
        - `code2` string, nullable: Artist country code (ISO 3166-1 alpha-2).
        - `image_url` string, nullable: Artist image URL.
        - `career_health` string, nullable: Artist career trend category (e.g. `decline`, `gradual decline`, `steady`, `gradual incline`, `incline`, `breakout`).
        - `career_stage` string, nullable: Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`).
        - `network_strength` object, nullable: Per-platform network-strength signals (Instagram, YouTube, etc.).
          - `label` string, nullable: Overall network-strength label.
          - `score` number, float, nullable: Overall normalized network-strength score (0–1).
          - `instagram_label` string, nullable: Descriptive label for Instagram performance.
          - `instagram_score` number, float, nullable: Normalized Instagram network-strength score (0–1).
          - `youtube_label` string, nullable: Descriptive label for YouTube performance.
          - `youtube_score` number, float, nullable: Normalized YouTube network-strength score (0–1).
      - object[]
    - `id` integer, nullable: Platform-specific row ID echoed back by the chart query (legacy).
    - `name` string, nullable: Track name.
    - `isrc` string, nullable: International Standard Recording Code.
    - `image_url` string, nullable: Track or album cover image URL.
    - `cm_track` integer, nullable: Chartmetric track ID.
    - `track_genre` union: Track genre(s) — string or array of strings depending on the source.
      - string
      - unknown[]
        - unknown
    - `spotify_popularity` integer, nullable: Spotify popularity score (0–100).
    - `spotify_duration_ms` integer, nullable: Track duration on Spotify in milliseconds.
    - `spotify_album_id` string, nullable: Spotify album ID associated with the track.
    - `composer_name` string, nullable: Composer name(s).
    - `cm_artist` integer[], nullable: Chartmetric artist IDs of the track artists.
    - `artist_names` string[], nullable: Track artist names.
    - `code2s` string[], nullable: ISO 3166-1 alpha-2 country codes per artist.
    - `artist_images` string[], nullable: Artist profile image URLs.
    - `artist_covers` string[], nullable: Artist cover image URLs.
    - `spotify_artist_ids` union[], nullable: Spotify artist IDs of the track artists.
      - union
        - integer
        - string
    - `spotify_artist_names` string[], nullable: Spotify artist names.
    - `spotify_track_ids` string[], nullable: Spotify track IDs.
    - `spotify_album_ids` string[], nullable: Spotify album IDs.
    - `itunes_artist_ids` union[], nullable: iTunes artist IDs.
      - union
        - integer
        - string
    - `itunes_artist_names` string[], nullable: iTunes artist names.
    - `itunes_track_ids` string[], nullable: iTunes track IDs.
    - `itunes_album_ids` string[], nullable: iTunes album IDs.
    - `storefronts` string[], nullable: Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available.
    - `album_ids` integer[], nullable: Chartmetric album IDs of the album(s) containing this track.
    - `album_names` string[], nullable: Album names.
    - `album_upc` string[], nullable: Album UPC (Universal Product Code) values.
    - `album_label` string[], nullable: Record labels for the album(s).
    - `release_dates` string[], nullable: Album release dates.

---

[API](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api.md) - [All operations](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/revisions/94dac96833a3?raw)