---
title: "Apple App Store Search"
method: POST
path: "/v1/apple/app-store/search"
tags: ["Apple"]
---

# Apple App Store Search

`POST /v1/apple/app-store/search`

## Request

- Base URL: `https://api.prismcrawl.com`
- URL: `https://api.prismcrawl.com/v1/apple/app-store/search`
- Auth: API key in header `x-api-key`

Search Apple App Store apps, optionally by developer name, genre, or explicit-content setting. Filter and paginate Apple’s returned inventory of up to 200 apps. Continuations bind the filters and ordered inventory; source ranking changes end pagination.

## Request body

- CatalogAppleAppStoreRequest: Search Apple App Store apps, optionally by developer name, genre, or explicit-content setting. Filter and paginate Apple’s returned inventory of up to 200 apps. Continuations bind the filters and ordered inventory; source ranking changes end pagination.
  - `query` string, required: Text to search for on the selected service. At most 8,192 UTF-8 bytes.
  - `country` string: Two-letter country or storefront code, such as us or gb.
  - `language` 'ca' | 'ca-es' | 'cs' | 'cs-cz' | 'da' | 'da-dk' | 'de' | 'de-ch' | 'de-de' | 'el' | 'el-gr' | 'en' | 'en-au' | 'en-ca' | 'en-gb' | 'en-us' | 'es' | 'es-es' | 'es-mx' | 'fi' | 'fi-fi' | 'fr' | 'fr-ca' | 'fr-fr' | 'hi' | 'hi-in' | 'hr' | 'hr-hr' | 'hu' | 'hu-hu' | 'id' | 'id-id' | 'it' | 'it-it' | 'ja' | 'ja-jp' | 'ko' | 'ko-kr' | 'ms' | 'ms-my' | 'nl' | 'nl-nl' | 'no' | 'no-no' | 'pl' | 'pl-pl' | 'pt' | 'pt-br' | 'pt-pt' | 'ro' | 'ro-ro' | 'ru' | 'ru-ru' | 'sk' | 'sk-sk' | 'sv' | 'sv-se' | 'th' | 'th-th' | 'tr' | 'tr-tr' | 'uk' | 'uk-ua' | 'vi' | 'vi-vi' | 'zh' | 'zh-cn' | 'zh-hk' | 'zh-tw': Provider-supported language code, such as en.
  - `category` 'software' | 'iPadSoftware' | 'macSoftware': A category identifier supported by this operation.
  - `disallow_explicit` boolean: Exclude explicit apps using the native explicit-content control.
  - `property` 'developer': Match the query against developer names within Apple’s returned search inventory.
  - `category_id` integer: Keep apps with this native genre ID within Apple’s returned search inventory.
  - `limit` integer: Maximum number of items to return. The provider may return fewer.
  - `device` 'desktop' | 'mobile' | 'tablet': Device presentation for the source request.
  - `next_page_token` string: Continue within Apple's returned catalog inventory, up to 200 apps per search. Use the same account, query, category, country, language, device, and result limit. The opaque token expires after one hour. Expired tokens are rejected before execution. If Apple's inventory changes during a valid continuation, the completed response costs one credit and marks pagination_reason: stale_cursor; restart the search.
  - `html` boolean: Return the encoded original response rather than parsed JSON.
  - `zero_trace` boolean: Do not archive source or parsed response artifacts.
  - `output` 'json' | 'html' | 'md' | 'null', nullable: Response content format. md returns Markdown in data.content with data.format=md; the JSON success/request envelope remains. Accept: text/markdown also selects Markdown unless output or html=true is explicit. html is an alias for html=true and retains the existing Brotli/Base64 source format.
  - `json_restrictor` string, nullable: Select fields within data.content for JSON or Markdown. Supports comma-separated paths, non-negative array indices, half-open slices [0:3] (either bound may be omitted), [] and .{nested,subqueries}. Up to128 selections and16 levels. Missing fields are omitted; selected declared fields retain their zero defaults. The request envelope and credit headers remain. Include next_page_token when pagination is needed. Incompatible with HTML output. This changes response presentation only; tracing-enabled history retains the complete JSON result.
  - `no_cache` boolean, nullable: Accepted for compatibility. Searches are always fetched without a result cache for either value; normal successful-request billing applies.

## Response `200`

Request completed. One credit is charged, including recognized empty or unavailable source results and source inventory changes discovered after a valid continuation is fetched. These completed responses may preserve verified partial results; operational failures remain errors.

- CatalogAppleAppStoreResponse
  - `success` true, required
  - `request_id` string, uuid, required
  - `data` union, required
    - MarkdownSearchData
      - `format` union, required
        - ''
        - 'md'
      - `content` string, required: Markdown derived from the parsed result, after any json_restrictor selection.
    - ProjectedSearchData
      - `format` union, required
        - ''
        - 'json'
      - `content` object, required: Only fields selected by json_restrictor. Selected fields retain their declared types and zero defaults.
    - object
      - `format` 'json', required
      - `content` object, required
        - `has_next_page` boolean, required
        - `next_page_token` string, required: Opaque continuation token valid for one hour and the same account. Retain search parameters, device, and result limit. Restart pagination if the token is expired or rejected; tokens from before the authenticated-token rollout cannot be reused.
        - `results` object[], required
          - `author` string, required
          - `authors` string[], required
          - `bundle_id` string, required
          - `category` string, required
          - `category_id` string, required
          - `content_rating` string, required
          - `currency` string, required
          - `description` string, required
          - `developer` string, required
          - `developer_id` string, required
          - `developer_url` string, required
          - `developer_website` string, required
          - `duration` string, required
          - `duration_minutes` number, required
          - `free` boolean, required
          - `genres` string[], required
          - `id` string, required
          - `information` object[], required
            - `name` string, required
            - `values` string[], required
          - `installs` string, required
          - `ipad_screenshots` string[], required
          - `isbn` string, required
          - `languages` string[], required
          - `minimum_installs` number, required
          - `minimum_os_version` string, required
          - `name` string, required
          - `operating_system` string, required
          - `pages` number, required
          - `position` integer, required
          - `price` number, required
          - `price_text` string, required
          - `published` string, required
          - `publisher` string, required
          - `rank` integer, required
          - `rating` number, required
          - `rating_count` number, required
          - `release_notes` string, required
          - `released` string, required
          - `screenshots` string[], required
          - `summary` string, required
          - `supported_devices` string[], required
          - `thumbnail` string, required
          - `title` string, required
          - `type` string, required
          - `updated` string, required
          - `url` string, required
          - `version` string, required
          - `version_text` string, required
        - `search_parameters` object, required
          - `category` string, required
          - `category_id` integer, required
          - `country` string, required
          - `device` string, required
          - `disallow_explicit` boolean, required
          - `engine` string, required
          - `language` string, required
          - `limit` integer, required
          - `operation` string, required
          - `pagination_limit` integer, required: Apple's maximum catalog inventory for one query. Continuation pages stay within the returned inventory.
          - `pagination_limited` boolean, required: True when further pagination is unavailable. A completed source-stale request can contain verified results or an empty array; next_page_token is an empty string.
          - `pagination_reason` string, required: stale_cursor means a valid continuation was fetched but its source inventory changed. The HTTP 200 response is billable; keep any verified results and restart pagination.
          - `property` string, required
          - `query` string, required
          - `source` string, required
          - `source_result_count` integer, required
          - `type` string, required
          - `url` string, required
        - `serp_features` object[], required
          - `confidence` number, required
          - `engine` string, required
          - `extracted_at` string, required
          - `id` string, required
          - `items` object[], required
            - `link` string, required
            - `product_id` string, required
            - `text` string, required
            - `thumbnail` string, required
            - `title` string, required
          - `links` object[], required
            - `title` string, required
            - `url` string, required
          - `position` object, required
            - `absolute` integer, required
          - `source_result_ids` string[], required
          - `text` string, required
          - `title` string, required
          - `type` string, required
    - GoogleHtmlSearchData
      - `format` union, required
        - ''
        - 'html+br+base64'
      - `content` string, byte, required: Base64-encoded bytes. Decode Base64 first, then decompress the result with Brotli. Available deferred or lazy-loaded thumbnail sources are placed in image src attributes, within size limits; image and video files are not downloaded. When rewrite_links is true, already-resolved opaque Google anchor links use their destination URLs. Unresolved links are preserved.

## Other responses

- `400`: The JSON body, source selection, or continuation is invalid. Locally malformed, forged, expired, or mismatched tokens are rejected before source work and require restarting pagination. A source may also reject an otherwise well-formed selector after acquisition. These errors do not spend a search credit. Source inventory changes discovered during a valid request return a completed response instead.
- `401`: The API token is missing, invalid, expired, or revoked.
- `402`: No credits remain.
- `429`: Account rate limit exceeded.
- `500`: The request could not be completed.

---

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