# Get Apple charts

Read the latest stored Apple free, paid or grossing chart for one storefront and category.

## Endpoint: GET /v1/charts

- Method: `GET`
- Path: `/v1/charts`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `get_market`
- MCP action: `charts`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | query | ^[a-z]{2}$ | no | Apple storefront. Defaults to us. Coverage is us, gb, fr, de, br, be, jp, kr, cn, ru. |
| `categoryId` | query | all or digits | no | Overall (all) or an Apple category id. Defaults to all. |
| `chartType` | query | free | paid | grossing | no | Apple chart type. Defaults to free. Grossing is a position, not dollars. |
| `view` | query | rankings | gainers | losers | new-entrants | new-releases | no | Leaderboard slice. Defaults to rankings. |
| `limit` | query | integer, 1–100 | no | Page size. Defaults to 100. |

## Known errors

- 400 invalid_request for an invalid filter, identity or limit.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing scope or unavailable preview access.
- 403 workspace_not_accessible when x-genviral-tenancy names a workspace the credential cannot reach.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.
- 429 daily_call_limit; the plan's daily API and MCP calls are used until 00:00 UTC.

## Request

Send country, categoryId, chartType, view and limit as query parameters. This GET never calls Apple.

```
curl --get 'https://api.peekpanda.com/v1/charts' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --data-urlencode 'country=us' \
  --data-urlencode 'categoryId=all' \
  --data-urlencode 'chartType=free' \
  --data-urlencode 'view=rankings' \
  --data-urlencode 'limit=100'
```

## MCP request

Call get_market with action charts. Path fields go in params, filters in query, and a write body in body.

```
{
  "name": "get_market",
  "arguments": {
    "request": {
      "action": "charts"
    }
  }
}

```

## Response

The response includes query, coverage, snapshot, summary, insights and data. Dates use ISO format, URLs are included when present, and estimates are optional. Estimates are worldwide monthly figures, whichever storefront the chart is for: a range (a low, mid and high reading) or below_floor when the app sits under the 5,000 a month the model can resolve. 0000000000 is a synthetic store ID.

```
{
  "query": {
    "country": "us",
    "categoryId": "all",
    "chartType": "free",
    "view": "rankings",
    "limit": 100
  },
  "coverage": {
    "countries": [
      {
        "code": "us",
        "name": "United States"
      },
      {
        "code": "gb",
        "name": "United Kingdom"
      },
      {
        "code": "fr",
        "name": "France"
      },
      {
        "code": "de",
        "name": "Germany"
      },
      {
        "code": "br",
        "name": "Brazil"
      },
      {
        "code": "be",
        "name": "Belgium"
      },
      {
        "code": "jp",
        "name": "Japan"
      },
      {
        "code": "kr",
        "name": "South Korea"
      },
      {
        "code": "cn",
        "name": "China"
      },
      {
        "code": "ru",
        "name": "Russia"
      }
    ],
    "categories": [
      {
        "id": "all",
        "name": "Overall"
      }
    ],
    "chartTypes": [
      "free",
      "paid",
      "grossing"
    ]
  },
  "snapshot": {
    "id": "chart-snapshot-example",
    "day": "2026-09-06",
    "sourceUpdatedAt": "2026-09-06T00:00:00.000Z",
    "fetchedAt": "2026-09-06T00:15:00.000Z",
    "depth": 100,
    "previousDay": "2026-09-05",
    "stale": false
  },
  "summary": {
    "trackedApps": 1,
    "rankedApps": 1,
    "gainers": 0,
    "losers": 0,
    "newEntrants": 0,
    "newReleases": 0
  },
  "insights": {
    "categoryMix": [
      {
        "categoryId": "6013",
        "name": "Health & Fitness",
        "count": 1
      }
    ],
    "releaseAges": [
      {
        "label": "1-3years",
        "count": 1
      }
    ],
    "categoryLeaders": [
      {
        "categoryId": "6013",
        "name": "Health & Fitness",
        "storeId": "0000000000",
        "appName": "Example Calorie Tracker",
        "iconUrl": "https://example.com/icon.png",
        "day": "2026-09-06",
        "depth": 100
      }
    ],
    "storefronts": [
      {
        "country": "us",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "gb",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "fr",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "de",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "br",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "be",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "jp",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "kr",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "cn",
        "day": "2026-09-06",
        "depth": 100
      },
      {
        "country": "ru",
        "day": "2026-09-06",
        "depth": 100
      }
    ]
  },
  "data": [
    {
      "storeId": "0000000000",
      "name": "Example Calorie Tracker",
      "developer": "Example Labs",
      "iconUrl": "https://example.com/icon.png",
      "appUrl": "https://apps.apple.com/us/app/id0000000000",
      "categoryId": "6013",
      "categoryName": "Health & Fitness",
      "releaseDate": "2024-05-01",
      "price": 0,
      "currency": "USD",
      "rating": 4.7,
      "ratingCount": 12450,
      "metadataUpdatedAt": "2026-09-06T00:15:00.000Z",
      "history": [
        {
          "day": "2026-09-06",
          "rank": 1
        }
      ],
      "rank": 1,
      "previousRank": 2,
      "movement": 1,
      "status": "ranked",
      "inCatalogue": true,
      "estimates": {
        "monthlyInstalls": {
          "kind": "range",
          "scope": "worldwide",
          "range": {
            "low": 40000,
            "mid": 84000,
            "high": 170000
          },
          "observedAt": "2026-09-06T00:00:00.000Z",
          "previous": {
            "kind": "range",
            "scope": "worldwide",
            "range": {
              "low": 34000,
              "mid": 72000,
              "high": 150000
            },
            "observedAt": "2026-09-05T00:00:00.000Z"
          }
        },
        "monthlyRevenue": {
          "kind": "below_floor",
          "scope": "worldwide",
          "ceiling": 5000,
          "observedAt": "2026-09-06T00:00:00.000Z",
          "previous": null
        },
        "currency": "USD"
      }
    }
  ],
  "updatedAt": "2026-09-06T00:15:00.000Z"
}

```

## Source

Dated public App Store chart observations. Grossing is a position, not a revenue amount, and this read returns a stored snapshot.

## Refresh

New snapshots are collected asynchronously. Completed historical snapshots remain unchanged.