GeckoAPI
Entrar Começar grátis

// docs

Amazon PLP

Extrai listagem de produtos (PLP) da Amazon com paginação.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Nesta documentação, os exemplos de output são preenchidos intencionalmente com valores não nulos para facilitar integração.

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 '{
  "url": "https://www.amazon.com.br/s?k=echo+dot",
  "target": "amazon.com.br",
  "type": "plp",
  "page": 1
}'

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

amazon_com_br_plp

Auth

Bearer ou X-API-Key

amazon_com_br_plp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "amazon_com_br_plp",
    "arguments": {
      "url": "https://www.amazon.com.br/s?k=echo+dot",
      "page": 1,
      "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
url
URL alvo da extração. Para alguns PLPs pode ser omitida quando a API monta a URL a partir de outros campos.
 string (URL) Condicional Obrigatorio somente quando keyword nao for enviada. - https://www.mercadolivre.com.br/p/MLB123456
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 Condicional Obrigatorio quando url nao for enviada. - iphone 15 pro max
priceMin
Preço mínimo para busca no Zapimoveis PLP.
 integer Opcional Preco minimo em reais inteiros; enviado na URL como low-price. - 1000
priceMax
Preço máximo para busca no Zapimoveis PLP.
 integer Opcional Preco maximo em reais inteiros; enviado na URL como high-price. - 2000
target
Fonte alvo da extração.
 enum Obrigatório Sempre obrigatorio no payload e deve combinar com o seam. - mercadolivre.com.br
type
Tipo da extração: pdp, idp, plp, quote, review ou places.
 enum Obrigatório Sempre obrigatorio no payload e deve combinar com o seam. - pdp
page
Paginacao. Em PLP inicia em 1; em review (MercadoLivre, Booking e Hoteis) inicia em 0.
 integer Opcional Suportado para PLP; deve ser inteiro >= 1. - 2

Exemplos de request

PLP por URL

Consulta de listagem informando URL e pagina.

PLP por URL 
{
  "url": "https://www.amazon.com.br/s?k=echo+dot",
  "target": "amazon.com.br",
  "type": "plp",
  "page": 1
}

PLP por keyword (sem url)

Gateway monta a URL de busca com base na keyword.

PLP por keyword (sem url) 
{
  "keyword": "echo dot",
  "target": "amazon.com.br",
  "type": "plp",
  "page": 1
}

PLP com faixa de preco

Busca por keyword com preco minimo e maximo.

PLP com faixa de preco 
{
  "keyword": "echo dot",
  "target": "amazon.com.br",
  "type": "plp",
  "page": 1,
  "priceMin": 500,
  "priceMax": 600
}

Schema de response (leaf paths)

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

responseSchema 
{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.query": "string",
  "data.totalResults": "number",
  "data.primaryResults": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].url": "string",
  "data.items[].sku": "string",
  "data.items[].name": "string",
  "data.items[].currency": "string",
  "data.items[].currencyRaw": "string",
  "data.items[].price": "number",
  "data.items[].aggregateRating.rating": "number",
  "data.items[].aggregateRating.reviewCount": "number",
  "data.items[].asin": "string",
  "data.items[].thumbnail": "string",
  "data.items[].sponsored": "boolean",
  "data.items[].prime": "boolean"
}

Exemplo de response

responseExample 
{
  "requestId": "55555555-1111-4111-8111-555555555555",
  "executionId": "55555555-2222-4222-8222-555555555555",
  "data": {
    "source": "amazon.com.br",
    "type": "plp",
    "url": "https://www.amazon.com.br/s?k=echo+dot",
    "requestUrl": "https://www.amazon.com.br/s?k=echo+dot&page=1",
    "extractedAt": "2026-02-12T13:01:00.000Z",
    "query": "echo dot",
    "totalResults": 1200,
    "primaryResults": 48,
    "page": 1,
    "resultsPerPage": 48,
    "offset": 0,
    "nextPage": 2,
    "nextPageUrl": "https://www.amazon.com.br/s?k=echo+dot&page=2",
    "items": [
      {
        "url": "https://www.amazon.com.br/dp/B09B8QFYZ2",
        "sku": "B09B8QFYZ2",
        "name": "Echo Dot 4a geracao",
        "currency": "BRL",
        "currencyRaw": "R$",
        "price": 379,
        "aggregateRating": {
          "rating": 4.8,
          "reviewCount": 10234
        },
        "asin": "B09B8QFYZ2",
        "thumbnail": "https://m.media-amazon.com/images/I/echo-dot-thumb.jpg",
        "sponsored": false,
        "prime": true
      }
    ]
  }
}

Referência completa de campos

Path Tipo Descrição Exemplo
data.extractedAt string (iso datetime) Campo data.extractedAt retornado no payload de resposta. 2026-02-12T13:01:00.000Z
data.items[].aggregateRating.rating number Campo data.items[].aggregateRating.rating retornado no payload de resposta. 4.8
data.items[].aggregateRating.reviewCount number Campo data.items[].aggregateRating.reviewCount retornado no payload de resposta. 10234
data.items[].asin string Campo data.items[].asin retornado no payload de resposta. B09B8QFYZ2
data.items[].currency string Campo data.items[].currency retornado no payload de resposta. BRL
data.items[].currencyRaw string Campo data.items[].currencyRaw retornado no payload de resposta. R$
data.items[].name string Campo data.items[].name retornado no payload de resposta. Echo Dot 4a geracao
data.items[].price number Campo data.items[].price retornado no payload de resposta. 379
data.items[].prime boolean Campo data.items[].prime retornado no payload de resposta. true
data.items[].sku string Campo data.items[].sku retornado no payload de resposta. B09B8QFYZ2
data.items[].sponsored boolean Campo data.items[].sponsored retornado no payload de resposta. false
data.items[].thumbnail string Campo data.items[].thumbnail retornado no payload de resposta. https://m.media-amazon.com/images/I/echo-dot-thumb.jpg
data.items[].url string Campo data.items[].url retornado no payload de resposta. https://www.amazon.com.br/dp/B09B8QFYZ2
data.nextPage number Campo data.nextPage retornado no payload de resposta. 2
data.nextPageUrl string Campo data.nextPageUrl retornado no payload de resposta. https://www.amazon.com.br/s?k=echo+dot&page=2
data.offset number Campo data.offset retornado no payload de resposta. 0
data.page number Campo data.page retornado no payload de resposta. 1
data.primaryResults number Campo data.primaryResults retornado no payload de resposta. 48
data.query string Campo data.query retornado no payload de resposta. echo dot
data.requestUrl string Campo data.requestUrl retornado no payload de resposta. https://www.amazon.com.br/s?k=echo+dot&page=1
data.resultsPerPage number Campo data.resultsPerPage retornado no payload de resposta. 48
data.source string Campo data.source retornado no payload de resposta. amazon.com.br
data.totalResults number Campo data.totalResults retornado no payload de resposta. 1200
data.type string Campo data.type retornado no payload de resposta. plp
data.url string Campo data.url retornado no payload de resposta. https://www.amazon.com.br/s?k=echo+dot
executionId string (uuid) Campo executionId retornado no payload de resposta. 55555555-2222-4222-8222-555555555555
notFound boolean (optional; true when the upstream entity was not found and data is null) Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully. N/A
requestId string (uuid) Campo requestId retornado no payload de resposta. 55555555-1111-4111-8111-555555555555

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.