GeckoAPI
PT EN
Entrar Testar URL

// docs

iFood PLP

Extrai listagem de lojas do iFood por CEP ou latitude/longitude, com keyword opcional, incluindo nota e contagem publica de avaliacoes quando o upstream expoe esse dado.

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 '{
  "target": "ifood.com.br",
  "type": "plp",
  "keyword": "marmita",
  "zipCode": "80010-000",
  "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

ifood_com_br_plp

Auth

Bearer ou X-API-Key

ifood_com_br_plp tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "ifood_com_br_plp",
    "arguments": {
      "keyword": "marmita",
      "zipCode": "80010-000",
      "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
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 Opcional Opcional. Quando enviada, o worker usa o endpoint search/results; quando omitida, usa o feed home pela localizacao. - iphone 15 pro max
zipCode
CEP brasileiro usado em APIs com resolucao geografica automatica. No iFood PLP, pode ser substituido por latitude + longitude. A API aceita com ou sem hifen e normaliza para 8 digitos.
 string (CEP) Condicional Obrigatorio quando latitude/longitude nao forem enviados. Pode ser null quando latitude e longitude forem enviados juntos. - 80010-000
latitude
Latitude da area de busca. Deve ser enviada junto com longitude. Suportada em iFood PLP, Airbnb PLP, Zap Imóveis PLP, Chaves na Mão PLP e Webmotors PLP.
 number Condicional Obrigatoria junto com longitude quando zipCode nao for enviado. Pode ser null quando zipCode existir. - -25.4284
longitude
Longitude da area de busca. Deve ser enviada junto com latitude. Suportada em iFood PLP, Airbnb PLP, Zap Imóveis PLP, Chaves na Mão PLP e Webmotors PLP.
 number Condicional Obrigatoria junto com latitude quando zipCode nao for enviado. Pode ser null quando zipCode existir. - -49.2733
target
Fonte alvo da extração.
 enum Obrigatório Sempre obrigatorio no payload e deve ser ifood.com.br. - mercadolivre.com.br
type
Tipo da extração: pdp, idp, plp, quote, review ou places.
 enum Obrigatório Sempre obrigatorio no payload e deve ser plp. - 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. 1 2

Exemplos de request

PLP por keyword + CEP

Fluxo recomendado: informe keyword e CEP; o worker geocodifica o CEP antes de consultar o endpoint do iFood.

PLP por keyword + CEP 
{
  "target": "ifood.com.br",
  "type": "plp",
  "keyword": "marmita",
  "zipCode": "80010-000",
  "page": 1
}

PLP por keyword + coordenadas

Informe latitude e longitude quando ja tiver as coordenadas da area. Neste modo, zipCode pode ser omitido ou enviado como null.

PLP por keyword + coordenadas 
{
  "target": "ifood.com.br",
  "type": "plp",
  "keyword": "marmita",
  "zipCode": null,
  "latitude": -25.4284,
  "longitude": -49.2733,
  "page": 1
}

PLP por CEP

Sem keyword, o worker geocodifica o CEP e usa o feed home do iFood para descobrir lojas na area. Nesse fluxo, a resposta tambem pode incluir userRatingCount quando a listagem exibe a contagem publica de avaliacoes.

PLP por CEP 
{
  "target": "ifood.com.br",
  "type": "plp",
  "zipCode": "80010-000",
  "page": 1
}

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.keyword": "string | null",
  "data.query": "string | null",
  "data.zipCode": "string | null",
  "data.latitude": "number",
  "data.longitude": "number",
  "data.geocoderProvider": "string",
  "data.sectionId": "string",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.primaryResults": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.nextCursor": "string",
  "data.items[].position": "number",
  "data.items[].id": "string",
  "data.items[].name": "string",
  "data.items[].url": "string",
  "data.items[].action": "string",
  "data.items[].merchantType": "string",
  "data.items[].slug": "string",
  "data.items[].mainCategory": "string",
  "data.items[].available": "boolean",
  "data.items[].availableForScheduling": "boolean",
  "data.items[].isIfoodDelivery": "boolean",
  "data.items[].isFavorite": "boolean",
  "data.items[].isNew": "boolean",
  "data.items[].isSuperRestaurant": "boolean",
  "data.items[].supportsTracking": "boolean",
  "data.items[].currency": "string",
  "data.items[].userRating": "number",
  "data.items[].userRatingCount": "number",
  "data.items[].distanceKm": "number",
  "data.items[].thumbnail": "string",
  "data.items[].deliveryInfo.type": "string",
  "data.items[].deliveryInfo.mode": "string",
  "data.items[].deliveryInfo.feeCents": "number",
  "data.items[].deliveryInfo.fee": "number",
  "data.items[].deliveryInfo.timeMinMinutes": "number",
  "data.items[].deliveryInfo.timeMaxMinutes": "number",
  "data.items[].deliveryInfo.nextSchedulingSlotStartTime": "string",
  "data.items[].deliveryInfo.nextSchedulingSlotEndTime": "string",
  "data.items[].formattedContent.firstLine": "string",
  "data.items[].formattedContent.secondLine": "string"
}

Exemplo de response

responseExample 
{
  "requestId": "55555555-1111-4111-8111-555555555555",
  "executionId": "55555555-2222-4222-8222-555555555555",
  "data": {
    "source": "ifood.com.br",
    "type": "plp",
    "url": "https://cw-marketplace.ifood.com.br/v2/cardstack/search/results?alias=SEARCH_RESULTS_MERCHANT_TAB_GLOBAL&channel=IFOOD&size=20&term=marmita&zipCode=80010000",
    "requestUrl": "https://cw-marketplace.ifood.com.br/v2/cardstack/search/results?alias=SEARCH_RESULTS_MERCHANT_TAB_GLOBAL&latitude=-25.4284&longitude=-49.2733&channel=IFOOD&size=20&term=marmita",
    "extractedAt": "2026-02-18T13:25:00.000Z",
    "keyword": "marmita",
    "query": "marmita",
    "zipCode": "80010000",
    "latitude": -25.4284,
    "longitude": -49.2733,
    "geocoderProvider": "brasilapi",
    "sectionId": "7519c970-d372-4552-b767-f0616e25697c",
    "page": 1,
    "resultsPerPage": 20,
    "offset": 0,
    "primaryResults": 20,
    "nextPage": 2,
    "nextPageUrl": "https://cw-marketplace.ifood.com.br/v2/cardstack/search/results?alias=SEARCH_RESULTS_MERCHANT_TAB_GLOBAL&latitude=-25.4284&longitude=-49.2733&channel=IFOOD&size=20&term=marmita&section=7519c970-d372-4552-b767-f0616e25697c&cursor=BHBzAMjA7vQBAKCz_IMTAMKA6ucPAKi31bceAPilq-INAMLBv_YWAKSVkrcaAOClztEOAAIAyAE%3D",
    "nextCursor": "BHBzAMjA7vQBAKCz_IMTAMKA6ucPAKi31bceAPilq-INAMLBv_YWAKSVkrcaAOClztEOAAIAyAE=",
    "items": [
      {
        "position": 1,
        "id": "9a7ea6c8-4493-44f0-a0be-f892b0a16941",
        "name": "Oh My Bread Padaria Artesanal Boulevard Curitibano",
        "url": "https://www.ifood.com.br/merchant?identifier=9a7ea6c8-4493-44f0-a0be-f892b0a16941&name=Oh%20My%20Bread%20Padaria%20Artesanal%20Boulevard%20Curitibano&slug=curitiba-pr/oh-my-bread-padaria-artesanal-boulevard-curitibano-vila-izabel&deliveryMethodCode=DEFAULT",
        "action": "merchant?identifier=9a7ea6c8-4493-44f0-a0be-f892b0a16941&name=Oh%20My%20Bread%20Padaria%20Artesanal%20Boulevard%20Curitibano&slug=curitiba-pr/oh-my-bread-padaria-artesanal-boulevard-curitibano-vila-izabel&deliveryMethodCode=DEFAULT",
        "merchantType": "merchant",
        "slug": "curitiba-pr/oh-my-bread-padaria-artesanal-boulevard-curitibano-vila-izabel",
        "mainCategory": "Padaria",
        "available": true,
        "availableForScheduling": true,
        "isIfoodDelivery": true,
        "isFavorite": false,
        "isNew": true,
        "isSuperRestaurant": true,
        "supportsTracking": true,
        "currency": "BRL",
        "userRating": 4.9,
        "userRatingCount": 421,
        "distanceKm": 2.87,
        "thumbnail": "https://static-images.ifood.com.br/image/upload/logosgde/9a7ea6c8-4493-44f0-a0be-f892b0a16941/202512221122_PVbJ_i.jpg",
        "deliveryInfo": {
          "type": "SCHEDULE",
          "mode": "DEFAULT",
          "feeCents": 1099,
          "fee": 10.99,
          "timeMinMinutes": 41,
          "timeMaxMinutes": 51,
          "nextSchedulingSlotStartTime": "2026-02-18T12:00:00-03:00",
          "nextSchedulingSlotEndTime": "2026-02-18T12:30:00-03:00"
        },
        "formattedContent": {
          "firstLine": "[#FFC347: Novidade!] [#666666: •] [#666666: Padaria] [#666666: •] [#666666: 2,9 km]",
          "secondLine": "Entrega rapida"
        }
      }
    ]
  }
}

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-18T13:25:00.000Z
data.geocoderProvider string Origem das coordenadas usadas na busca, incluindo input_coordinates quando latitude/longitude foram enviados diretamente. brasilapi
data.items[].action string Campo data.items[].action retornado no payload de resposta. merchant?identifier=9a7ea6c8-4493-44f0-a0be-f892b0a16941&name=Oh%20My%20Bread%20Padaria%20Artesanal%20Boulevard%20Curitibano&slug=curitiba-pr/oh-my-bread-padaria-artesanal-boulevard-curitibano-vila-izabel&deliveryMethodCode=DEFAULT
data.items[].available boolean Campo data.items[].available retornado no payload de resposta. true
data.items[].availableForScheduling boolean Campo data.items[].availableForScheduling retornado no payload de resposta. true
data.items[].currency string Campo data.items[].currency retornado no payload de resposta. BRL
data.items[].deliveryInfo.fee number Campo data.items[].deliveryInfo.fee retornado no payload de resposta. 10.99
data.items[].deliveryInfo.feeCents number Campo data.items[].deliveryInfo.feeCents retornado no payload de resposta. 1099
data.items[].deliveryInfo.mode string Campo data.items[].deliveryInfo.mode retornado no payload de resposta. DEFAULT
data.items[].deliveryInfo.nextSchedulingSlotEndTime string Campo data.items[].deliveryInfo.nextSchedulingSlotEndTime retornado no payload de resposta. 2026-02-18T12:30:00-03:00
data.items[].deliveryInfo.nextSchedulingSlotStartTime string Campo data.items[].deliveryInfo.nextSchedulingSlotStartTime retornado no payload de resposta. 2026-02-18T12:00:00-03:00
data.items[].deliveryInfo.timeMaxMinutes number Campo data.items[].deliveryInfo.timeMaxMinutes retornado no payload de resposta. 51
data.items[].deliveryInfo.timeMinMinutes number Campo data.items[].deliveryInfo.timeMinMinutes retornado no payload de resposta. 41
data.items[].deliveryInfo.type string Campo data.items[].deliveryInfo.type retornado no payload de resposta. SCHEDULE
data.items[].distanceKm number Campo data.items[].distanceKm retornado no payload de resposta. 2.87
data.items[].formattedContent.firstLine string Campo data.items[].formattedContent.firstLine retornado no payload de resposta. [#FFC347: Novidade!] [#666666: •] [#666666: Padaria] [#666666: •] [#666666: 2,9 km]
data.items[].formattedContent.secondLine string Campo data.items[].formattedContent.secondLine retornado no payload de resposta. Entrega rapida
data.items[].id string Campo data.items[].id retornado no payload de resposta. 9a7ea6c8-4493-44f0-a0be-f892b0a16941
data.items[].isFavorite boolean Campo data.items[].isFavorite retornado no payload de resposta. false
data.items[].isIfoodDelivery boolean Campo data.items[].isIfoodDelivery retornado no payload de resposta. true
data.items[].isNew boolean Campo data.items[].isNew retornado no payload de resposta. true
data.items[].isSuperRestaurant boolean Campo data.items[].isSuperRestaurant retornado no payload de resposta. true
data.items[].mainCategory string Campo data.items[].mainCategory retornado no payload de resposta. Padaria
data.items[].merchantType string Campo data.items[].merchantType retornado no payload de resposta. merchant
data.items[].name string Campo data.items[].name retornado no payload de resposta. Oh My Bread Padaria Artesanal Boulevard Curitibano
data.items[].position number Campo data.items[].position retornado no payload de resposta. 1
data.items[].slug string Campo data.items[].slug retornado no payload de resposta. curitiba-pr/oh-my-bread-padaria-artesanal-boulevard-curitibano-vila-izabel
data.items[].supportsTracking boolean Campo data.items[].supportsTracking retornado no payload de resposta. true
data.items[].thumbnail string Campo data.items[].thumbnail retornado no payload de resposta. https://static-images.ifood.com.br/image/upload/logosgde/9a7ea6c8-4493-44f0-a0be-f892b0a16941/202512221122_PVbJ_i.jpg
data.items[].url string Campo data.items[].url retornado no payload de resposta. https://www.ifood.com.br/merchant?identifier=9a7ea6c8-4493-44f0-a0be-f892b0a16941&name=Oh%20My%20Bread%20Padaria%20Artesanal%20Boulevard%20Curitibano&slug=curitiba-pr/oh-my-bread-padaria-artesanal-boulevard-curitibano-vila-izabel&deliveryMethodCode=DEFAULT
data.items[].userRating number Nota publica da loja quando a listagem expoe esse dado. 4.9
data.items[].userRatingCount number Contagem publica de avaliacoes exibida pelo upstream quando disponivel, especialmente nos cards do feed home por CEP. 421
data.keyword string | null Keyword enviada no payload; null quando a busca foi feita apenas por CEP. marmita
data.latitude number Latitude usada na chamada ao iFood; vem do CEP geocodificado ou das coordenadas enviadas. -25.4284
data.longitude number Longitude usada na chamada ao iFood; vem do CEP geocodificado ou das coordenadas enviadas. -49.2733
data.nextCursor string Campo data.nextCursor retornado no payload de resposta. BHBzAMjA7vQBAKCz_IMTAMKA6ucPAKi31bceAPilq-INAMLBv_YWAKSVkrcaAOClztEOAAIAyAE=
data.nextPage number Campo data.nextPage retornado no payload de resposta. 2
data.nextPageUrl string Campo data.nextPageUrl retornado no payload de resposta. https://cw-marketplace.ifood.com.br/v2/cardstack/search/results?alias=SEARCH_RESULTS_MERCHANT_TAB_GLOBAL&latitude=-25.4284&longitude=-49.2733&channel=IFOOD&size=20&term=marmita&section=7519c970-d372-4552-b767-f0616e25697c&cursor=BHBzAMjA7vQBAKCz_IMTAMKA6ucPAKi31bceAPilq-INAMLBv_YWAKSVkrcaAOClztEOAAIAyAE%3D
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. 20
data.query string | null Espelha data.keyword; null quando a busca foi feita apenas por CEP. marmita
data.requestUrl string Campo data.requestUrl retornado no payload de resposta. https://cw-marketplace.ifood.com.br/v2/cardstack/search/results?alias=SEARCH_RESULTS_MERCHANT_TAB_GLOBAL&latitude=-25.4284&longitude=-49.2733&channel=IFOOD&size=20&term=marmita
data.resultsPerPage number Campo data.resultsPerPage retornado no payload de resposta. 20
data.sectionId string Campo data.sectionId retornado no payload de resposta. 7519c970-d372-4552-b767-f0616e25697c
data.source string Campo data.source retornado no payload de resposta. ifood.com.br
data.type string Campo data.type retornado no payload de resposta. plp
data.url string Campo data.url retornado no payload de resposta. https://cw-marketplace.ifood.com.br/v2/cardstack/search/results?alias=SEARCH_RESULTS_MERCHANT_TAB_GLOBAL&channel=IFOOD&size=20&term=marmita&zipCode=80010000
data.zipCode string | null CEP normalizado usado na consulta, ou null quando a chamada foi feita somente com latitude/longitude. 80010000
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.