--- title: "Shazam Track Charts" method: GET path: "/api/charts/shazam" tags: ["Charts"] --- # Shazam Track Charts `GET /api/charts/shazam` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/charts/shazam` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Shazam track charts with country/city/genre filters. Handler switches between the city-level and genre-level SQL queries, then merges iTunes-linked track metadata and a `countries_charting_count` derived from a global ranking map. ## Query parameters - `country_code` union, required: ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts. - string: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB'). - 'GLOBAL' - `date` string, date-time: Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`. - `city` string: Shazam chart city. May return no results when `country_code=GLOBAL`. Use `/api/charts/shazam/{country_code}/cities` to list valid cities. - `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate. - `latest` boolean: If true, use the most recently available date and ignore `date`. - `genre` 'alternative' | 'rock' | 'french-pop' | 'film-tv-and-stage' | 'randb-soul' | 'latin' | 'reggae-dancehall' | 'k-pop' | 'hip-hop-rap' | 'worldwide' | 'singer-songwriter' | 'dance' | 'afrobeats' | 'house' | 'electronic' | 'pop' | 'country' | 'regional-mexicano': Shazam genre filter; if omitted, returns chart for all genres. ## Response `200` Success - object - `obj` object - `length` integer, nullable: Number of chart rows in `data`. - `data` object[], nullable: Chart rows ordered by rank (1 = highest). - `id` union: Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups). - integer - string - `name` string, nullable: Track name. - `isrc` string, nullable: International Standard Recording Code. - `image_url` string, nullable: Track or album cover image URL. - `description` string, nullable: Track description (free-text metadata). - `tags` string, nullable: Comma-separated genre tags for the track. - `cm_track` integer, nullable: Chartmetric track ID. - `cm_artist` integer[], nullable: Chartmetric artist IDs of the track artists. - `artist_names` string[], nullable: Track artist names. - `code2s` string[], nullable: Country codes per artist (ISO 3166-1 alpha-2). - `artist_images` string[], nullable: Artist profile image URLs. - `artist_covers` string[], nullable: Artist cover image URLs. - `spotify_track_ids` string[], nullable: Spotify track IDs. - `spotify_album_ids` string[], nullable: Spotify album IDs. - `spotify_duration_ms` integer, nullable: Track duration on Spotify in milliseconds. - `itunes_track_ids` string[], nullable: iTunes track IDs. - `itunes_album_ids` string[], nullable: iTunes album IDs. - `itunes_artist_ids` union[], nullable: iTunes artist IDs. - union - integer - string - `itunes_artist_names` string[], nullable: iTunes artist names. - `storefronts` string[], nullable: iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased). - `deezer_track_ids` string[], nullable: Deezer track IDs. - `deezer_album_ids` union[], nullable: Deezer album IDs. - union - number, float - string - `deezer_duration` integer, nullable: Track duration on Deezer in seconds. - `amazon_track_ids` string[], nullable: Amazon track IDs. - `amazon_album_ids` string[], nullable: Amazon album IDs. - `album_ids` union[], nullable: Chartmetric album IDs. - union - integer - string - `album_names` string[], nullable: Album names. - `album_upc` string[], nullable: Album UPC values. - `album_label` string[], nullable: Record labels for the album(s). - `release_dates` union[], nullable: Album release dates. - union - string, date-time - string - `created_at` union: Track-record creation timestamp. - string, date-time - string - `modified_at` union: Track-record last-modified timestamp. - string, date-time - string - `rank` integer, nullable: Current chart rank (1 = top). - `pre_rank` integer, nullable: Position on the previous chart period. - `peak_rank` integer, nullable: Best (lowest-numbered) rank reached. - `peak_date` union: Date `peak_rank` was achieved. - string, date-time - string - `added_at` union: Timestamp the row was added to the chart. - string, date-time - string - `velocity` number, float, nullable: Rank-velocity signal (positive = climbing). - `time_on_chart` union: Length of time on the chart. - string - number, float - `code2` string, nullable: Chart country code (ISO 3166-1 alpha-2). - `city` string, nullable: Chart city name (when chart is city-scoped). - `genre` string, nullable: Chart genre filter applied to the row. - `shazam_track_id` union: Shazam track ID. Deprecated by Shazam and no longer populated after January 2024. - string - number, float - `itunes_id` union: iTunes ID for the track linked to this Shazam row. - string - number, float - `itunes_track_id` string, nullable: iTunes track ID (string from track basic info). - `itunes_album_id` union: iTunes album ID(s) for the track. - string[] - string, nullable - `num_of_shazams` union: Total Shazam tag count for the track. - number, float - string - `countries_charting_count` integer, nullable: Number of countries on which this track is currently charting on Shazam. - `rankStats` object[], nullable: Per-row historical rank samples. - `rank` integer, nullable: Rank at `timestp` (1 = top). - `timestp` union: Timestamp of the rank sample. - string, date-time - string --- [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)