AppStore API endpoint
Returns the curated editorial shelves from one of Apple's per-device App Store landing pages (the same content shown by apps.apple.com's device switcher). `device` enum: `iphone`, `ipad`, `mac`, `vision`, `watch`, `tv`. `section` enum: `main` (the device's Today/Discover/Apps & Games landing page), `arcade` (the device's Apple Arcade landing page). Watch has no Arcade page — `device=watch` with `section=arcade` returns `400`.
/appstore/editorialMCP tool: appstore_editorial
Query parameters:
device: required. Apple device catalog, using apps.apple.com's own URL
vocabulary. Allowed values: iphone, ipad, mac, vision, watch, tv.section: optional. Editorial section within the device. Default main.
Allowed values: main (the device's Today/Discover/Apps & Games landing
page), arcade (the device's Apple Arcade landing page). watch has no
Arcade page — device=watch with section=arcade returns 400.country: optional. Two-letter storefront country code.lang: optional. Result language tag.Each shelf's items is a best-effort normalization of Apple's own
heterogeneous editorial item shapes (individual apps, category links,
promotional cards) — fields are populated when present and simply absent
otherwise, so a promotional card without an app ID has id/bundle_id
omitted while title/url are still populated. The shelf titled
"Browse by Category" has items whose destination_id is the numeric
editorial page ID to pass as category_id to appstore_editorial_category
for the SAME device — note destination_id is not unique to that shelf: a
regular single-app item also carries one (its own ID, a self-referential
page link), so scope to the "Browse by Category" shelf by title when
looking for a category ID rather than taking the first destination_id
found on the page.
Example response (device=vision):
{
"code": 200,
"msg": "OK",
"data": {
"device": "vision",
"section": "main",
"title": "Apps & Games",
"seo_title": "Apps & Games for Vision - App Store",
"page_id": "6442720677",
"shelves": [
{
"id": "shelf_eds.20684838-fafb-4c26-b7a0-8fb0980a2e9e",
"title": "What's New",
"content_type": "smallLockup",
"items": [
{
"kind": "Lockup",
"id": 6753299273,
"bundle_id": "com.lamborghini.visionpro",
"title": "Lamborghini",
"subtitle": "Lifestyle",
"developer_name": "Automobili Lamborghini S.p.A.",
"age_rating": "4+",
"icon_url": "https://is1-ssl.mzstatic.com/image/thumb/...",
"url": "https://apps.apple.com/us/app/lamborghini/id6753299273"
}
]
},
{
"id": "shelf_eds.c355fd32-a03d-453b-a975-e07ba69ddcb7",
"title": "Browse by Category",
"content_type": "smallBrick",
"items": [
{
"kind": "Brick",
"title": "Entertainment Apps",
"url": "https://apps.apple.com/us/vision/editorial/6503709728",
"destination_id": "6503709728"
}
]
}
]
}
}
| Field | Filled in, of 29 checked | Values in the sample |
|---|---|---|
| id | 28 | |
| content_type | 29 | “heroCarousel” and 9 other values |
| items | 29 | median 10 entries |
| title | 25 | median 27 characters |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| device | string | Yes | Apple device catalog Allowed values: iphone, ipad, mac, vision, watch, tv. | iphone | |
| section | string | No | Editorial section within the device Allowed values: main, arcade. | ||
| country | string | No | Two-letter storefront country code | us | |
| lang | string | No | Result language tag | en-us | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/appstore/editorial?device=iphone§ion=main&country=us&lang=en" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"device": "vision",
"section": "main",
"title": "Apps & Games",
"seo_title": "Apps & Games for Vision - App Store",
"page_id": "6442720677",
"shelves": [
{
"id": "shelf_eds.20684838-fafb-4c26-b7a0-8fb0980a2e9e",
"title": "What's New",
"content_type": "smallLockup",
"items": [
{
"kind": "Lockup",
"id": 6753299273,
"bundle_id": "com.lamborghini.visionpro",
"title": "Lamborghini",
"subtitle": "Lifestyle",
"developer_name": "Automobili Lamborghini S.p.A.",
"age_rating": "4+",
"icon_url": "https://is1-ssl.mzstatic.com/image/thumb/...",
"url": "https://apps.apple.com/us/app/lamborghini/id6753299273"
}
]
},
{
"id": "shelf_eds.c355fd32-a03d-453b-a975-e07ba69ddcb7",
"title": "Browse by Category",
"content_type": "smallBrick",
"items": [
{
"kind": "Brick",
"title": "Entertainment Apps",
"url": "https://apps.apple.com/us/vision/editorial/6503709728",
"destination_id": "6503709728"
}
]
}
]
}
}Request schema
No body schema
Response schema
#/definitions/appstore.editorialResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | appstore.EditorialPage | No | ||||
| data.device | string | No | Apple device catalog of the page: `iphone`, `ipad`, `mac`, `vision`, `watch` or `tv`. | |||
| data.page_id | string | No | Apple's ID for the editorial page. | |||
| data.section | string | No | main | arcade | category | |||
| data.seo_title | string | No | Page title used for search results and browser tabs. | |||
| data.shelves | array | No | Content shelves on the page, in display order. EditorialShelf record, 16 fields: content_type, id, items, title. Described under App Store Editorial Category Page API. | |||
| data.title | string | No | Title of the editorial page. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Missing or invalid parameters | #/definitions/app.Response |
| 404 | Page not found | #/definitions/app.Response |
| 429 | Rate limit exceeded | #/definitions/app.Response |
| 500 | Internal server error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/appstore/editorial?device=iphone§ion=main&country=us&lang=en" \
-H "x-api-key: $CRAWLORA_API_KEY"