// docs

App Store: Search apps and ads

Query organic results and ads from App Store's native search in Brazil and the United States. 5 credits per call.

apps.apple.com:plp · 5 credits per request

Standard credit cost. Your account pricing is shown in the sandbox.

When to use this operation

The query includes ads published by the App Store and may wait before retrying when the upstream source rate-limits requests. Set a client timeout of at least 120 seconds. If rate limiting persists, the API returns HTTP 429 with errorCode=UPSTREAM_RATE_LIMITED, a Retry-After header and retryAfterSeconds in the body; wait for that interval before retrying. Credits are refunded for requests ending in this failure. Responses with ads=[] are valid and do not trigger retries.

Source-specific limitations

The query uses native App Store search without an Apple ID. Ad availability varies by keyword, country and time; ads=[] is valid. Pagination is not supported in this version. The response preserves native JSON, whose structure can vary. The abbreviated example comes from a real capture on 27/10/2026 and shows two organic resources and one ad; event metadata and other attributes were omitted only from the example. It does not promise ad delivery or ranking in future requests.

HTTP request

cURL

curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "apps.apple.com",
  "type": "plp",
  "keyword": "spotify",
  "region": "BR"
}'

Keep your API key on your server. See the quickstart for authentication and response handling.

MCP request

The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.

POST /v1/mcp · Bearer or X-API-Key authentication

apps_apple_com_plp · tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "apps_apple_com_plp",
    "arguments": {
      "keyword": "spotify",
      "region": "BR",
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.

Field	Type	Requirement	Rule	Default	Example
keyword Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL.	string	Required	Search term with 1 to 200 characters, after removing external spaces.	-	spotify
region Query region. The format depends on API; Temu PDP accepts br (Brazil), us (United States), uk (United Kingdom) and co (Colombia); PLP accepts br, us and uk. The default of Temu without country in URL is br and OLX accepts a textual region.	string	Optional	BR (Brazil) or US (United States). Selects the storefront, language and country used for the outbound request.	BR	BR
target Target source for extraction.	enum	Required	Use apps.apple.com.	apps.apple.com	apps.apple.com
type Extraction type: pdp, idp, plp, ilp, quote, review or places.	enum	Required	Use plp.	plp	plp

Request examples

Search in Brazil

Spotify query on the Brazilian storefront with network output in Brazil.

Search in Brazil

{
  "target": "apps.apple.com",
  "type": "plp",
  "keyword": "spotify",
  "region": "BR"
}

Search in the United States

Weather query on the American storefront with network output in the United States.

Search in the United States

{
  "target": "apps.apple.com",
  "type": "plp",
  "keyword": "weather",
  "region": "US"
}

Response schema

Leaf paths and expected types. Field names and enum values are part of the API contract.

responseSchema

{
  "requestId": "string",
  "executionId": "string",
  "data.source": "string",
  "data.type": "string",
  "data.query": "string",
  "data.region": "string",
  "data.extractedAt": "string",
  "data.organicCount": "number",
  "data.adCount": "number",
  "data.ads[]": "object",
  "data.ads[].id": "string",
  "data.ads[].type": "string",
  "data.ads[].attributes": "object",
  "data.ads[].attributes.name": "string",
  "data.ads[].attributes.artistName": "string",
  "data.ads[].attributes.url": "string",
  "data.ads[].attributes.userRating": "object",
  "data.ads[].meta": "object | undefined",
  "data.nativeResponse": "object",
  "data.nativeResponse.results.search.data[]": "object",
  "data.nativeResponse.results.ads-result": "object | undefined",
  "data.nativeResponse.meta": "object | undefined"
}

Example response

Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.

responseExample

{
  "requestId": "example-request",
  "executionId": "example-execution",
  "data": {
    "source": "apps.apple.com",
    "type": "plp",
    "query": "spotify",
    "region": "BR",
    "extractedAt": "2026-10-27T20:20:02.330783Z",
    "organicCount": 248,
    "adCount": 1,
    "ads": [
      {
        "id": "6477489729",
        "type": "apps",
        "attributes": {
          "name": "Google Gemini",
          "artistName": "Google",
          "url": "https://apps.apple.com/br/app/google-gemini/id6477489729",
          "userRating": {
            "ariaLabelForRatings": "4.8 estrelas",
            "ratingCount": 934598,
            "ratingCountList": [
              32496,
              7257,
              11342,
              29137,
              854366
            ],
            "value": 4.8
          },
          "genreDisplayName": "Produtividade"
        },
        "meta": {}
      }
    ],
    "nativeResponse": {
      "results": {
        "ads-result": {
          "data": [
            {
              "id": "6477489729",
              "type": "apps",
              "attributes": {
                "name": "Google Gemini",
                "artistName": "Google",
                "url": "https://apps.apple.com/br/app/google-gemini/id6477489729",
                "userRating": {
                  "ariaLabelForRatings": "4.8 estrelas",
                  "ratingCount": 934598,
                  "ratingCountList": [
                    32496,
                    7257,
                    11342,
                    29137,
                    854366
                  ],
                  "value": 4.8
                },
                "genreDisplayName": "Produtividade"
              },
              "meta": {}
            }
          ]
        },
        "search": {
          "data": [
            {
              "id": "324684580",
              "type": "apps",
              "attributes": {
                "name": "Spotify: músicas e podcasts",
                "artistName": "Spotify",
                "url": "https://apps.apple.com/br/app/spotify-m%C3%BAsicas-e-podcasts/id324684580",
                "userRating": {
                  "ariaLabelForRatings": "4.9 estrelas",
                  "ratingCount": 11224403,
                  "ratingCountList": [
                    159871,
                    70689,
                    163290,
                    468298,
                    10362255
                  ],
                  "value": 4.9
                },
                "genreDisplayName": "Música"
              }
            },
            {
              "id": "544007664",
              "type": "apps",
              "attributes": {
                "name": "YouTube",
                "artistName": "Google",
                "url": "https://apps.apple.com/br/app/youtube/id544007664",
                "userRating": {
                  "ariaLabelForRatings": "4.7 estrelas",
                  "ratingCount": 7412698,
                  "ratingCountList": [
                    196396,
                    88862,
                    187458,
                    499737,
                    6440245
                  ],
                  "value": 4.7
                },
                "genreDisplayName": "Foto e vídeo"
              }
            }
          ]
        }
      },
      "meta": {}
    }
  }
}

Complete field reference

Path	Type	Description	Example
data.adCount	number	Number of ads returned in this query; zero is a valid result.	1
data.ads[]	object	Native sponsored resource, preserved without destructive normalization.	{"id":"6477489729","type":"apps","attributes":{"name":"Google Gemini","artistName":"Google","url":"https://apps.apple.com/br/app/google-gemini/id6477489729","userRating":{"ariaLabelForRatings":"4.8 estrelas","ratingCount":934598,"ratingCountList":[32496,7257,11342,29137,854366],"value":4.8},"genreDisplayName":"Produtividade"},"meta":{}}
data.ads[].attributes	object	Native attributes, including images and platform-specific information when published.	{"name":"Google Gemini","artistName":"Google","url":"https://apps.apple.com/br/app/google-gemini/id6477489729","userRating":{"ariaLabelForRatings":"4.8 estrelas","ratingCount":934598,"ratingCountList":[32496,7257,11342,29137,854366],"value":4.8},"genreDisplayName":"Produtividade"}
data.ads[].attributes.artistName	string	Published developer name.	Google
data.ads[].attributes.name	string	Name of the advertised application.	Google Gemini
data.ads[].attributes.url	string	URL public application.	https://apps.apple.com/br/app/google-gemini/id6477489729
data.ads[].attributes.userRating	object	Assessment object published by App Store.	{"ariaLabelForRatings":"4.8 estrelas","ratingCount":934598,"ratingCountList":[32496,7257,11342,29137,854366],"value":4.8}
data.ads[].id	string	Identifier of the advertised application.	6477489729
data.ads[].meta	object \| undefined	Native advertising metadata, including extraAdInfo when available. Optional and dynamic fields; Event URLs are not triggered by GeckoAPI.	{}
data.ads[].type	string	Resource type returned by Apple.	apps
data.extractedAt	string	Collection date and time in UTC.	2026-10-27T20:20:02.330783Z
data.nativeResponse	object	Complete JSON response from the App Store application search, including results, relationships, and native metadata.	{"results":{"ads-result":{"data":[{"id":"6477489729","type":"apps","attributes":{"name":"Google Gemini","artistName":"Google","url":"https://apps.apple.com/br/app/google-gemini/id6477489729","userRating":{"ariaLabelForRatings":"4.8 estrelas","ratingCount":934598,"ratingCountList":[32496,7257,11342,29137,854366],"value":4.8},"genreDisplayName":"Produtividade"},"meta":{}}]},"search":{"data":[{"id":"324684580","type":"apps","attributes":{"name":"Spotify: músicas e podcasts","artistName":"Spotify","url":"https://apps.apple.com/br/app/spotify-m%C3%BAsicas-e-podcasts/id324684580","userRating":{"ariaLabelForRatings":"4.9 estrelas","ratingCount":11224403,"ratingCountList":[159871,70689,163290,468298,10362255],"value":4.9},"genreDisplayName":"Música"}},{"id":"544007664","type":"apps","attributes":{"name":"YouTube","artistName":"Google","url":"https://apps.apple.com/br/app/youtube/id544007664","userRating":{"ariaLabelForRatings":"4.7 estrelas","ratingCount":7412698,"ratingCountList":[196396,88862,187458,499737,6440245],"value":4.7},"genreDisplayName":"Foto e vídeo"}}]}},"meta":{}}
data.nativeResponse.meta	object \| undefined	Search metadata published by the source, when present.	{}
data.nativeResponse.results.ads-result	object \| undefined	Native advertising block, when present.	{"data":[{"id":"6477489729","type":"apps","attributes":{"name":"Google Gemini","artistName":"Google","url":"https://apps.apple.com/br/app/google-gemini/id6477489729","userRating":{"ariaLabelForRatings":"4.8 estrelas","ratingCount":934598,"ratingCountList":[32496,7257,11342,29137,854366],"value":4.8},"genreDisplayName":"Produtividade"},"meta":{}}]}
data.nativeResponse.results.search.data[]	object	Organic resource in the order returned by the source. It can represent apps or other types of content.	{"id":"324684580","type":"apps","attributes":{"name":"Spotify: músicas e podcasts","artistName":"Spotify","url":"https://apps.apple.com/br/app/spotify-m%C3%BAsicas-e-podcasts/id324684580","userRating":{"ariaLabelForRatings":"4.9 estrelas","ratingCount":11224403,"ratingCountList":[159871,70689,163290,468298,10362255],"value":4.9},"genreDisplayName":"Música"}}
data.organicCount	number	Number of resources in organic search. May include apps and editorial content.	248
data.query	string	Keyword used in the search.	spotify
data.region	string	Storefront consulted: BR or US. The network output follows the selected country.	BR
data.source	string	Source: apps.apple.com.	apps.apple.com
data.type	string	Type: plp.	plp
executionId	string	Execution identifier.	example-execution
requestId	string	Request identifier HTTP in GeckoAPI.	example-request

Errors and missing data

When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.

HTTP status	Error code	Meaning
400	`INVALID_PAYLOAD`	Invalid JSON or a request that violates the documented validation rules.
401	`UNAUTHORIZED`	Missing authorization or an invalid API key or token.
402	`INSUFFICIENT_CREDITS`	The account has insufficient credits for this operation.
403	`FORBIDDEN`	The account does not have access, or the API is temporarily disabled.
409	`EXECUTION_CONFLICT`	The execution identifier conflicts with an incompatible execution state.
429	`RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS`	A rate limit or simultaneous request limit was exceeded.
5xx	`UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERROR`	An upstream, worker or gateway failure. Failed requests follow the platform refund policy.