Docs menu

Datasets API endpoint

Search the app-charts dataset API

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).

GETapiKey1 credit/record returned · minimum 2Datasetsdatasets.chartsSearchResponseDoc/datasets/apps-charts/search

Endpoint facts

Method: GET
API path: /datasets/apps-charts/search
Auth: apiKey
Credits: 1 credit/record returned · minimum 2
Charged on: Successful 2xx responses only
Platform: Datasets
Execution: Stored dataset records. No live scraping, browser session or proxy routing.
Response schema: #/definitions/datasets.chartsSearchResponseDoc

Stored structured dataset search API Try Search the app-charts dataset API in Playground Datasets API documentation

How this endpoint behaves

Searches daily top-chart snapshots scraped from the iOS App Store and Google Play, stored in a search index. One document per chart × snapshot × rank, so re-crawls accumulate a time series: today's chart, an app's rank over time, and day-over-day movers. Returns structured ranking records (rank, app id, title, developer, store, chart type, category, country, snapshot date) without triggering live scraping.

Dataset id enum:

apps-charts

Store enum:

ios
android

Query parameters:

q: optional full-text query over chart-entry title and developer, max 256 characters.
store: optional store enum: ios, android.
chart_type: optional chart enum: top_free, top_paid, top_grossing, new.
platform: optional Apple device-platform filter, iOS charts only. See platform enum above.
collection: optional raw store collection id filter (e.g. topgrossingapplications, GROSSING), max 128 characters.
category: optional store category/genre filter, max 128 characters. Empty for the overall (all-category) charts.
country: optional exact storefront country filter, max 128 characters, e.g. us.
app_id: optional exact app filter — the iOS numeric track id or the Android package name. Pair with sort=date_desc for an app's rank over time.
date: optional snapshot date filter, yyyy-MM-dd. Defaults to the latest available snapshot (today's chart).
sort: optional sort enum: rank (chart order), rank_desc, date_desc (rank over time). Defaults to rank.
page: optional page number, defaults to 1.
page_size: optional page size, defaults to 20 and maxes at 100.

Response behavior:

With no date (and no single-app history request) the latest snapshot is resolved automatically, so the default response is today's chart in rank order.
The response echoes the resolved snapshot_date so callers know which day was returned.
The maximum result window is 10000; page * page_size must not exceed 10000.
Invalid enum values return the standard invalid params envelope.
A not-yet-populated index returns an empty items list rather than an error.
iOS chart entries carry a platform field (see platform enum above); Android entries leave it empty.
Android chart snapshots include the overall Google Play app charts and selected category charts, including the GAME and FAMILY app categories.
Does not trigger live scraping.

Billing

1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.

Live monitoring

Monitored request: GET /datasets/apps-charts/search?page_size=2
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 0.82 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /datasets/apps-charts/search?chart_type=top_free&country=us&store=ios&page_size=20
Items in items: 20
Fields filled in every checked item: 14
Fields empty in some or all items: 1

Field	Filled in, of 20 checked	Values in the sample
chart_uid	20
store	20
collection	20
chart_type	20
platform	20
category	18	6,014 to 7,019, median 7,006
country	20
snapshot_date	20	2026-10-13
rank	20	1
app_id	20
title	20
developer	20
free	20	true in 20 of 20
url	20	apps.apple.com
crawled_at	20	2026-10-13

Request parameters

Parameter	Type	Required	Default	Description
q	string	No		Full-text query over chart-entry title and developer, max 256 characters
store	string	No		Store enum: ios, android Allowed values: ios, android.
chart_type	string	No		Chart enum: top_free, top_paid, top_grossing, new Allowed values: top_free, top_paid, top_grossing, new.
platform	string	No		Apple device-platform filter, iOS charts only; see platform enum above
collection	string	No		Raw store collection id filter (e.g. topgrossingapplications, GROSSING), max 128 characters
category	string	No		Store category/genre filter, max 128 characters; empty for the overall charts
country	string	No		Exact storefront country filter, max 128 characters
app_id	string	No		Exact app filter — iOS numeric track id or Android package; pair with sort=date_desc for rank history
date	string	No	the latest snapshot	Snapshot date filter yyyy-MM-dd; defaults to the latest snapshot
sort	string	No		Sort enum: rank, rank_desc, date_desc Allowed values: rank, rank_desc, date_desc.
page	integer	No	1	Page number, defaults to 1
page_size	integer	No	20 and maxes at 100	Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/datasets/apps-charts/search?q=coffee&store=ios&chart_type=top_free&country=us&sort=rank&page=1" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "dataset": "apps-charts",
    "items": [
      {
        "chart_uid": "android:GROSSING::jp:2026-06-19:1",
        "store": "android",
        "collection": "GROSSING",
        "chart_type": "top_grossing",
        "country": "jp",
        "snapshot_date": "2026-06-19",
        "rank": 1,
        "app_id": "com.google.android.apps.subscriptions.red",
        "title": "Google One",
        "developer": "Google LLC",
        "free": true,
        "url": "https://play.google.com/store/apps/details?id=com.google.android.apps.subscriptions.red"
      }
    ],
    "snapshot_date": "2026-06-19",
    "page": 1,
    "page_size": 20,
    "total": 100,
    "sort": "rank"
  }
}

Request schema

No body schema

Response schema

#/definitions/datasets.chartsSearchResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	datasets.ChartsSearchResponse	No
data.dataset	string	No		Identifier of the dataset queried (`apps-charts`).
data.items	array	No		App chart entries on this page.
data.items[].app_id	string	No		App id in the store: the numeric App Store id or the Google Play package name.
data.items[].category	string	No		Store category or genre the chart covers. Empty for the overall chart.
data.items[].chart_type	string	No		Kind of chart: `top_free`, `top_paid`, `top_grossing` or `new`.
data.items[].chart_uid	string	No		Unique id of this chart entry, combining store, collection, category, country, snapshot date and rank.
data.items[].collection	string	No		Store's own id for the chart, for example `topgrossingapplications` or `GROSSING`.
data.items[].country	string	No		Storefront country code of the chart, for example `us`.
data.items[].crawled_at	string	No		Time the chart was fetched, in UTC (RFC 3339).
data.items[].developer	string	No		Name of the app's developer or publisher as shown on the chart.
data.items[].free	boolean	No		Whether the app is free to download.
data.items[].platform	string	No		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.
data.items[].rank	integer	No		Position of the app in the chart, starting at 1.
data.items[].score	number	No		Average user rating of the app. Set for Google Play charts.
data.items[].snapshot_date	string	No		Date the chart was captured, in UTC (YYYY-MM-DD).
data.items[].store	string	No		Which store the chart belongs to: `ios` or `android`.
data.items[].title	string	No		App name as shown on the chart.
data.items[].url	string	No		Store page of the app.
data.page	integer	No		Page number returned.
data.page_size	integer	No		Number of items per page.
data.snapshot_date	string	No		Date of the chart snapshot returned, in YYYY-MM-DD.
data.sort	string	No		Sort order applied.
data.total	integer	No		Total number of records matching the filters.
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/datasets/apps-charts/search?q=coffee&store=ios&chart_type=top_free&country=us&sort=rank&page=1" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More Datasets endpoint docs Stored structured dataset search API Stored Datasets List API documentation Airbnb Markets Dataset Facets API documentation Airbnb Markets Dataset Country API documentation Nearby Airbnb Markets Dataset API documentation Airbnb Markets Dataset Search API documentation Facet the Apple Books dataset API documentation

Open in Playground Back to group

Docs menu

Datasets API endpoint

Search the app-charts dataset API

GETapiKey1 credit/record returned · minimum 2Datasetsdatasets.chartsSearchResponseDoc/datasets/apps-charts/search

Endpoint facts

Method: GET
API path: /datasets/apps-charts/search
Auth: apiKey
Credits: 1 credit/record returned · minimum 2
Charged on: Successful 2xx responses only
Platform: Datasets
Execution: Stored dataset records. No live scraping, browser session or proxy routing.
Response schema: #/definitions/datasets.chartsSearchResponseDoc

Stored structured dataset search API Try Search the app-charts dataset API in Playground Datasets API documentation

How this endpoint behaves

Dataset id enum:

apps-charts

Store enum:

ios
android

Query parameters:

q: optional full-text query over chart-entry title and developer, max 256 characters.
store: optional store enum: ios, android.
chart_type: optional chart enum: top_free, top_paid, top_grossing, new.
platform: optional Apple device-platform filter, iOS charts only. See platform enum above.
collection: optional raw store collection id filter (e.g. topgrossingapplications, GROSSING), max 128 characters.
category: optional store category/genre filter, max 128 characters. Empty for the overall (all-category) charts.
country: optional exact storefront country filter, max 128 characters, e.g. us.
app_id: optional exact app filter — the iOS numeric track id or the Android package name. Pair with sort=date_desc for an app's rank over time.
date: optional snapshot date filter, yyyy-MM-dd. Defaults to the latest available snapshot (today's chart).
sort: optional sort enum: rank (chart order), rank_desc, date_desc (rank over time). Defaults to rank.
page: optional page number, defaults to 1.
page_size: optional page size, defaults to 20 and maxes at 100.

Response behavior:

With no date (and no single-app history request) the latest snapshot is resolved automatically, so the default response is today's chart in rank order.
The response echoes the resolved snapshot_date so callers know which day was returned.
The maximum result window is 10000; page * page_size must not exceed 10000.
Invalid enum values return the standard invalid params envelope.
A not-yet-populated index returns an empty items list rather than an error.
iOS chart entries carry a platform field (see platform enum above); Android entries leave it empty.
Android chart snapshots include the overall Google Play app charts and selected category charts, including the GAME and FAMILY app categories.
Does not trigger live scraping.

Billing

Live monitoring

Monitored request: GET /datasets/apps-charts/search?page_size=2
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 0.82 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /datasets/apps-charts/search?chart_type=top_free&country=us&store=ios&page_size=20
Items in items: 20
Fields filled in every checked item: 14
Fields empty in some or all items: 1

Field	Filled in, of 20 checked	Values in the sample
chart_uid	20
store	20
collection	20
chart_type	20
platform	20
category	18	6,014 to 7,019, median 7,006
country	20
snapshot_date	20	2026-10-13
rank	20	1
app_id	20
title	20
developer	20
free	20	true in 20 of 20
url	20	apps.apple.com
crawled_at	20	2026-10-13

Request parameters

Parameter	Type	Required	Default	Description
q	string	No		Full-text query over chart-entry title and developer, max 256 characters
store	string	No		Store enum: ios, android Allowed values: ios, android.
chart_type	string	No		Chart enum: top_free, top_paid, top_grossing, new Allowed values: top_free, top_paid, top_grossing, new.
platform	string	No		Apple device-platform filter, iOS charts only; see platform enum above
collection	string	No		Raw store collection id filter (e.g. topgrossingapplications, GROSSING), max 128 characters
category	string	No		Store category/genre filter, max 128 characters; empty for the overall charts
country	string	No		Exact storefront country filter, max 128 characters
app_id	string	No		Exact app filter — iOS numeric track id or Android package; pair with sort=date_desc for rank history
date	string	No	the latest snapshot	Snapshot date filter yyyy-MM-dd; defaults to the latest snapshot
sort	string	No		Sort enum: rank, rank_desc, date_desc Allowed values: rank, rank_desc, date_desc.
page	integer	No	1	Page number, defaults to 1
page_size	integer	No	20 and maxes at 100	Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/datasets/apps-charts/search?q=coffee&store=ios&chart_type=top_free&country=us&sort=rank&page=1" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "dataset": "apps-charts",
    "items": [
      {
        "chart_uid": "android:GROSSING::jp:2026-06-19:1",
        "store": "android",
        "collection": "GROSSING",
        "chart_type": "top_grossing",
        "country": "jp",
        "snapshot_date": "2026-06-19",
        "rank": 1,
        "app_id": "com.google.android.apps.subscriptions.red",
        "title": "Google One",
        "developer": "Google LLC",
        "free": true,
        "url": "https://play.google.com/store/apps/details?id=com.google.android.apps.subscriptions.red"
      }
    ],
    "snapshot_date": "2026-06-19",
    "page": 1,
    "page_size": 20,
    "total": 100,
    "sort": "rank"
  }
}

Request schema

No body schema

Response schema

#/definitions/datasets.chartsSearchResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	datasets.ChartsSearchResponse	No
data.dataset	string	No		Identifier of the dataset queried (`apps-charts`).
data.items	array	No		App chart entries on this page.
data.items[].app_id	string	No		App id in the store: the numeric App Store id or the Google Play package name.
data.items[].category	string	No		Store category or genre the chart covers. Empty for the overall chart.
data.items[].chart_type	string	No		Kind of chart: `top_free`, `top_paid`, `top_grossing` or `new`.
data.items[].chart_uid	string	No		Unique id of this chart entry, combining store, collection, category, country, snapshot date and rank.
data.items[].collection	string	No		Store's own id for the chart, for example `topgrossingapplications` or `GROSSING`.
data.items[].country	string	No		Storefront country code of the chart, for example `us`.
data.items[].crawled_at	string	No		Time the chart was fetched, in UTC (RFC 3339).
data.items[].developer	string	No		Name of the app's developer or publisher as shown on the chart.
data.items[].free	boolean	No		Whether the app is free to download.
data.items[].platform	string	No		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.
data.items[].rank	integer	No		Position of the app in the chart, starting at 1.
data.items[].score	number	No		Average user rating of the app. Set for Google Play charts.
data.items[].snapshot_date	string	No		Date the chart was captured, in UTC (YYYY-MM-DD).
data.items[].store	string	No		Which store the chart belongs to: `ios` or `android`.
data.items[].title	string	No		App name as shown on the chart.
data.items[].url	string	No		Store page of the app.
data.page	integer	No		Page number returned.
data.page_size	integer	No		Number of items per page.
data.snapshot_date	string	No		Date of the chart snapshot returned, in YYYY-MM-DD.
data.sort	string	No		Sort order applied.
data.total	integer	No		Total number of records matching the filters.
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/datasets/apps-charts/search?q=coffee&store=ios&chart_type=top_free&country=us&sort=rank&page=1" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

Search the app-charts dataset API

Endpoint facts

How this endpoint behaves

Billing

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

Search the app-charts dataset API

Endpoint facts

How this endpoint behaves

Billing

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related