// docs

App Store — Busca e anúncios

Consulta resultados orgânicos e anúncios da busca nativa do App Store no Brasil e nos Estados Unidos. 5 créditos por chamada.

Quando usar este endpoint

A consulta inclui os anúncios publicados pela App Store e pode aguardar antes de repetir uma tentativa quando a origem limita as requisições. Configure um timeout de pelo menos 120 segundos no seu cliente. Se a limitação persistir, a API retorna HTTP 429 com errorCode=UPSTREAM_RATE_LIMITED, o cabeçalho Retry-After e retryAfterSeconds no corpo; aguarde esse intervalo antes de tentar novamente. Chamadas que terminam nessa falha têm os créditos devolvidos. Respostas com ads=[] são válidas e não provocam novas tentativas.

Testar este endpoint no sandbox

Tempo de resposta: A consulta usa a busca do aplicativo App Store, sem Apple ID. A disponibilidade de anúncios varia por palavra-chave, país e momento; ads=[] é válido. Não há paginação nesta versão. A resposta preserva o JSON nativo, cujo formato pode variar. Exemplo reduzido de uma coleta real em 27/10/2026: exibe dois recursos orgânicos e um anúncio; metadados de eventos e demais atributos foram omitidos somente do exemplo. Não representa uma promessa de anúncio ou ranking em novas consultas.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Consulte o schema e a descrição de cada campo para tratar valores ausentes; os exemplos mostram uma resposta possível.

Quando a entidade consultada não existe na origem, o extract e a tool MCP retornam 200 com data: null e notFound: true. Esse caso é tratado como resposta concluída, não como erro de servidor.

Chamada HTTP

cURL

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

Chamada MCP

A mesma seam também aparece no MCP hospedado como uma tool dedicada. Os argumentos reaproveitam os campos do extract, mas target e type já ficam fixos pela tool.

Ver guia completo do MCP

Endpoint

POST /v1/mcp

Tool name

apps_apple_com_plp

Auth

Bearer ou X-API-Key

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"
    }
  }
}

Possibilidades de input

Campos suportados nesta API do POST /v1/extract, com regras específicas de obrigatoriedade e condicionais.

Campo	Tipo	Status	Regra	Default	Exemplo
keyword Palavra-chave para buscas PLP. Em Google Search ela representa a query enviada ao Google; em Booking PLP é obrigatória; em outros PLPs pode substituir a URL.	string	Obrigatório	Termo de busca com 1 a 200 caracteres, após remover espaços externos.	-	spotify
region Região da consulta. O formato depende da API; Temu PDP aceita br (Brasil), us (Estados Unidos), uk (Reino Unido) e co (Colômbia); PLP aceita br, us e uk. O padrão da Temu sem país na URL é br e OLX aceita uma região textual.	string	Opcional	BR (Brasil) ou US (Estados Unidos). Define a storefront, idioma e país de saída da consulta.	BR	BR
target Fonte alvo da extração.	enum	Obrigatório	Use apps.apple.com.	apps.apple.com	apps.apple.com
type Tipo da extração: pdp, idp, plp, ilp, quote, review ou places.	enum	Obrigatório	Use plp.	plp	plp

Exemplos de request

Busca no Brasil

Consulta spotify na storefront brasileira com saída de rede no Brasil.

Busca no Brasil

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

Busca nos Estados Unidos

Consulta weather na storefront americana com saída de rede nos Estados Unidos.

Busca nos Estados Unidos

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

Schema de response (leaf paths)

Mapa de paths de saída com tipo esperado para esta API.

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"
}

Exemplo de response

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": {}
    }
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.adCount	number	Quantidade de anúncios retornados nesta consulta; zero é um resultado válido.	1
data.ads[]	object	Recurso patrocinado nativo, preservado sem normalização destrutiva.	{"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	Atributos nativos, incluindo imagens e informações específicas de plataforma quando publicados.	{"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	Nome do desenvolvedor publicado.	Google
data.ads[].attributes.name	string	Nome do aplicativo anunciado.	Google Gemini
data.ads[].attributes.url	string	URL pública do aplicativo.	https://apps.apple.com/br/app/google-gemini/id6477489729
data.ads[].attributes.userRating	object	Objeto de avaliações publicado pela App Store.	{"ariaLabelForRatings":"4.8 estrelas","ratingCount":934598,"ratingCountList":[32496,7257,11342,29137,854366],"value":4.8}
data.ads[].id	string	Identificador do aplicativo anunciado.	6477489729
data.ads[].meta	object \| undefined	Metadados publicitários nativos, incluindo extraAdInfo quando disponível. Campos opcionais e dinâmicos; URLs de eventos não são acionadas pela GeckoAPI.	{}
data.ads[].type	string	Tipo de recurso retornado pela Apple.	apps
data.extractedAt	string	Data e hora da coleta em UTC.	2026-10-27T20:20:02.330783Z
data.nativeResponse	object	Resposta JSON completa da busca do aplicativo App Store, incluindo resultados, relacionamentos e metadados nativos.	{"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	Metadados de busca publicados pela origem, quando presentes.	{}
data.nativeResponse.results.ads-result	object \| undefined	Bloco nativo de publicidade, quando presente.	{"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	Recurso orgânico na ordem retornada pela origem. Pode representar apps ou outros tipos de conteúdo.	{"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	Quantidade de recursos na busca orgânica. Pode incluir apps e conteúdo editorial.	248
data.query	string	Palavra-chave utilizada na busca.	spotify
data.region	string	Storefront consultada: BR ou US. A saída de rede acompanha o país selecionado.	BR
data.source	string	Origem: apps.apple.com.	apps.apple.com
data.type	string	Tipo: plp.	plp
executionId	string	Identificador da execução.	example-execution
requestId	string	Identificador da requisição HTTP na GeckoAPI.	example-request

Erros comuns

Respostas com notFound: true não entram nesta tabela, porque retornam sucesso HTTP 200.

Status	errorCode	Quando acontece
400	INVALID_PAYLOAD	JSON inválido ou violação das regras de validação do payload.
401	UNAUTHORIZED	Header Authorization ausente ou token/chave inválida.
402	INSUFFICIENT_CREDITS	Saldo de créditos insuficiente para a API solicitada.
403	FORBIDDEN	Usuário sem acesso ou API temporariamente desabilitada.
409	EXECUTION_CONFLICT	executionId conflita com uma execução em estado incompatível.
429	RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS	Limite de taxa ou limite de requisições em voo excedido.
5xx	UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR	Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente.