PLP por URL
Informa a URL de listagem e pagina explicitamente.
PLP por URL
{
"url": "https://lista.mercadolivre.com.br/iphone-15-pro-max",
"target": "mercadolivre.com.br",
"type": "plp",
"page": 2
}// docs
Mercado Livre PLP
Extrai listagem de produtos (PLP) do Mercado Livre 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.
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://lista.mercadolivre.com.br/iphone-15-pro-max",
"target": "mercadolivre.com.br",
"type": "plp",
"page": 2
}'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 Booking PLP é obrigatória; em outros PLPs pode substituir a URL. | string | Condicional | Obrigatorio quando url nao for enviada. | - | iphone 15 pro max |
| 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, plp ou review. | enum | Obrigatório | Sempre obrigatorio no payload e deve combinar com o seam. | - | pdp |
| page Paginação. Em PLP inicia em 1; em MercadoLivre review inicia em 0. | integer | Opcional | Suportado para PLP; deve ser inteiro >= 1. | - | 2 |
Exemplos de request
PLP por keyword (sem url)
Gateway monta a URL automaticamente a partir da keyword.
PLP por keyword (sem url)
{
"keyword": "iphone 15 pro max",
"target": "mercadolivre.com.br",
"type": "plp",
"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)",
"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[].condition": "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[].ean": "string",
"data.items[].sellerId": "string",
"data.items[].sellerName": "string",
"data.items[].sellerCity": "string",
"data.items[].sellerState": "string",
"data.items[].sellerCountry": "string"
}Exemplo de response
responseExample
{
"requestId": "22222222-1111-4111-8111-222222222222",
"executionId": "22222222-2222-4222-8222-222222222222",
"data": {
"source": "mercadolivre.com.br",
"type": "plp",
"url": "https://lista.mercadolivre.com.br/iphone-15-pro-max",
"requestUrl": "https://lista.mercadolivre.com.br/iphone-15-pro-max?_Desde=49",
"extractedAt": "2026-02-12T12:34:56.000Z",
"query": "iphone 15 pro max",
"totalResults": 4832,
"primaryResults": 1000,
"page": 2,
"resultsPerPage": 48,
"offset": 48,
"nextPage": 3,
"nextPageUrl": "https://lista.mercadolivre.com.br/iphone-15-pro-max?_Desde=97",
"items": [
{
"url": "https://www.mercadolivre.com.br/p/MLB3889019023",
"sku": "MLB3889019023",
"name": "Apple iPhone 15 Pro Max 256GB Titanio Natural",
"condition": "new",
"currency": "BRL",
"currencyRaw": "R$",
"price": 8499,
"aggregateRating": {
"rating": 4.8,
"reviewCount": 1250
},
"ean": "194253952768",
"sellerId": "123456789",
"sellerName": "Apple Store Oficial",
"sellerCity": "Sao Paulo",
"sellerState": "SP",
"sellerCountry": "Brasil"
}
]
}
}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-12T12:34:56.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. | 1250 |
| data.items[].condition | string | Campo data.items[].condition retornado no payload de resposta. | new |
| 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[].ean | string | Campo data.items[].ean retornado no payload de resposta. | 194253952768 |
| data.items[].name | string | Campo data.items[].name retornado no payload de resposta. | Apple iPhone 15 Pro Max 256GB Titanio Natural |
| data.items[].price | number | Campo data.items[].price retornado no payload de resposta. | 8499 |
| data.items[].sellerCity | string | Campo data.items[].sellerCity retornado no payload de resposta. | Sao Paulo |
| data.items[].sellerCountry | string | Campo data.items[].sellerCountry retornado no payload de resposta. | Brasil |
| data.items[].sellerId | string | Campo data.items[].sellerId retornado no payload de resposta. | 123456789 |
| data.items[].sellerName | string | Campo data.items[].sellerName retornado no payload de resposta. | Apple Store Oficial |
| data.items[].sellerState | string | Campo data.items[].sellerState retornado no payload de resposta. | SP |
| data.items[].sku | string | Campo data.items[].sku retornado no payload de resposta. | MLB3889019023 |
| data.items[].url | string | Campo data.items[].url retornado no payload de resposta. | https://www.mercadolivre.com.br/p/MLB3889019023 |
| data.nextPage | number | Campo data.nextPage retornado no payload de resposta. | 3 |
| data.nextPageUrl | string | Campo data.nextPageUrl retornado no payload de resposta. | https://lista.mercadolivre.com.br/iphone-15-pro-max?_Desde=97 |
| data.offset | number | Campo data.offset retornado no payload de resposta. | 48 |
| data.page | number | Campo data.page retornado no payload de resposta. | 2 |
| data.primaryResults | number | Campo data.primaryResults retornado no payload de resposta. | 1000 |
| data.query | string | Campo data.query retornado no payload de resposta. | iphone 15 pro max |
| data.requestUrl | string | Campo data.requestUrl retornado no payload de resposta. | https://lista.mercadolivre.com.br/iphone-15-pro-max?_Desde=49 |
| data.resultsPerPage | number | Campo data.resultsPerPage retornado no payload de resposta. | 48 |
| data.source | string | Campo data.source retornado no payload de resposta. | mercadolivre.com.br |
| data.totalResults | number | Campo data.totalResults retornado no payload de resposta. | 4832 |
| data.type | string | Campo data.type retornado no payload de resposta. | plp |
| data.url | string | Campo data.url retornado no payload de resposta. | https://lista.mercadolivre.com.br/iphone-15-pro-max |
| executionId | string (uuid) | ID de execucao para rastreio e deduplicacao. | 22222222-2222-4222-8222-222222222222 |
| requestId | string (uuid) | ID unico da requisicao no gateway. | 22222222-1111-4111-8111-222222222222 |
Erros comuns
| 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. |
| 500 | WORKER_ERROR / INTERNAL_ERROR | Falha interna no worker ou no gateway. |