---
title: "Search the app-charts dataset"
method: GET
path: "/datasets/apps-charts/search"
tags: ["Datasets"]
---

# Search the app-charts dataset

`GET /datasets/apps-charts/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/apps-charts/search`
- Auth: API key in header `x-api-key`

Searches daily top-chart snapshots from the iOS App Store and Google Play (one document per chart × snapshot × rank). With no `date` the latest snapshot is returned (today's chart); pair `app_id` with `sort=date_desc` for an app's rank over time. Store enum: `ios`, `android`. Chart type enum: `top_free`, `top_paid`, `top_grossing`, `new`. Platform enum (Apple device platforms, ios charts only): `phone`, `pad`, `mac`. Sort enum: `rank`, `rank_desc`, `date_desc`. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).

## Query parameters

- `q` string
- `store` 'ios' | 'android'
- `chart_type` 'top_free' | 'top_paid' | 'top_grossing' | 'new'
- `platform` string
- `collection` string
- `category` string
- `country` string
- `app_id` string
- `date` string
- `sort` 'rank' | 'rank_desc' | 'date_desc'
- `page` integer
- `page_size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsChartsSearchResponseDoc
  - `code` integer
  - `data` DatasetsChartsSearchResponse
    - `dataset` string: Identifier of the dataset queried (`apps-charts`).
    - `items` EsChartEntry[]: App chart entries on this page.
      - `app_id` string: App id in the store: the numeric App Store id or the Google Play package name.
      - `category` string: Store category or genre the chart covers. Empty for the overall chart.
      - `chart_type` string: Kind of chart: `top_free`, `top_paid`, `top_grossing` or `new`.
      - `chart_uid` string: Unique id of this chart entry, combining store, collection, category, country, snapshot date and rank.
      - `collection` string: Store's own id for the chart, for example `topgrossingapplications` or `GROSSING`.
      - `country` string: Storefront country code of the chart, for example `us`.
      - `crawled_at` string: Time the chart was fetched, in UTC (RFC 3339).
      - `developer` string: Name of the app's developer or publisher as shown on the chart.
      - `free` boolean: Whether the app is free to download.
      - `platform` string: Platform is the Apple device platform this chart ranking is for — phone, pad, or mac (Apple's appPlatforms vocabulary) — or empty for Google Play (Android has no separate device-family charts). A chart ranking is always single-platform by construction, unlike AppRecord.Platforms.
      - `rank` integer: Position of the app in the chart, starting at 1.
      - `score` number: Average user rating of the app. Set for Google Play charts.
      - `snapshot_date` string: Date the chart was captured, in UTC (YYYY-MM-DD).
      - `store` string: Which store the chart belongs to: `ios` or `android`.
      - `title` string: App name as shown on the chart.
      - `url` string: Store page of the app.
    - `page` integer: Page number returned.
    - `page_size` integer: Number of items per page.
    - `snapshot_date` string: Date of the chart snapshot returned, in YYYY-MM-DD.
    - `sort` string: Sort order applied.
    - `total` integer: Total number of records matching the filters.
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/028417aa35bb?raw)