Skip to content

Discover time series

Time series discovery retrieves measurements across a dataset for a requested date range. It combines partitioned discovery with time-window filtering.

Method Route Dataset
GET /api/app_estimates/discovery App estimates across stores.
GET /api/app_sessions/discovery App sessions across stores.
GET /api/publisher_estimates/discovery Publisher estimates across stores.
GET /api/:store/ratings/discovery App ratings for the selected store.
Parameter Required Description
partition Yes Partition to read, from 1 to total_partitions.
total_partitions Yes Integer from 100 to 10,000. Keep it constant throughout the run.
date_from Yes Start of the date range in YYYY-MM-DD format.
date_to Yes End of the date range. Use at most 180 days per request.
model_version Yes for app/publisher estimates; no for sessions Select v2.0 or v3.0 for app estimates, publisher estimates, or sessions discovery. Not used by ratings discovery.
page_token No Omit for the first page; use the preceding response’s next_page_token for later pages.

App and publisher estimates discovery return 400 if model_version is omitted. Sessions discovery accepts it as an optional parameter. The default described in Estimate model versions applies only where the parameter is optional.

App estimates, publisher estimates, and sessions discovery group result_rows by store. Each page contains rows for a single store. This abbreviated example shows a page of Apple App Store results:

{
"result_rows": {
"itunes_connect": [{ "id": 389801252, "date": "2016-06-10", "country_iso": "US" }]
},
"next_page_token": "NEXT_PAGE_TOKEN"
}

Follow page tokens within the same partition until next_page_token is absent. Split longer history into smaller date windows. See Discovery for pagination rules.

Ratings discovery returns a flat result_rows array for the store in the request path. In discovery records, Apple App Store app IDs and publisher IDs can be integers even when the corresponding lookup returns strings.