---
title: "Amazon Album Charts"
method: GET
path: "/api/charts/amazon/albums"
tags: ["Charts"]
---

# Amazon Album Charts

`GET /api/charts/amazon/albums`

## Request

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

Amazon album charts. Handler runs `QUERY_GET_AMAZON_ALBUM_CHARTS`, joins per-album metadata via `Album.getInfo("amazon", …)` (rows without matching album info are dropped), and attaches historical `rankStats` from `QUERY_GET_ALBUM_RANKINGS.AMAZON`.

## Query parameters

- `date` string, date-time: Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`.
- `genre` string, required: Amazon genre filter. Use `/api/charts/genres/amazon` to retrieve the available genre IDs/names.
- `code2` string: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').
- `type` 'popular_album' | 'new_album', required: Amazon album chart type (`popular_album` or `new_album`).
- `latest` boolean: If true, use the most recently available date and ignore `date`.
- `limit` integer: Maximum entries returned. Defaults to 500.
- `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
    - `length` integer, nullable: Number of chart rows in `data`.
    - `data` object[], nullable: Chart rows ordered by rank (1 = highest).
      - `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
      - `amazon_album` union: Amazon album row ID (numeric or string).
        - string
        - integer
      - `original_id` string, nullable: Original platform identifier echoed from the chart row.
      - `code2` string, nullable: Chart country code (ISO 3166-1 alpha-2).
      - `genre` string, nullable: Chart genre.
      - `id` union: Amazon album ID (from album-info join).
        - integer
        - string
      - `name` string, nullable: Album name.
      - `upc` string, nullable: Universal Product Code identifying the release.
      - `label` string, nullable: Record label that released the album.
      - `image_url` string, nullable: Album cover image URL.
      - `release_date` union: Album release date.
        - string, date-time
        - string
      - `cm_album` integer, nullable: Chartmetric album ID.
      - `num_track` union: Number of tracks on the album.
        - string
        - number, float
      - `amazon_album_ids` string[], nullable: Amazon album IDs.
      - `artists` object[], nullable: Artist info objects for the album.
      - `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)