// docs
Extrai listagem de veiculos (PLP) do Webmotors por cidade/UF.
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.
curl -X POST https://api.geckoapi.com.br/v1/extract \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"target": "webmotors.com.br",
"type": "plp",
"city": "Sao Jose dos Pinhais",
"state": "PR",
"usedCars": true,
"newCars": true,
"page": 1
}'
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) | Opcional | Opcional. Quando ausente, a URL e montada com city/state. | - | https://www.mercadolivre.com.br/p/MLB123456 |
| city Cidade usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com state). | string | Obrigatório | Obrigatorio para PLP de Webmotors. | - | Sao Paulo |
| state UF usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com city). | string (UF 2 letras) | Obrigatório | Obrigatorio para PLP de Webmotors (UF com 2 letras). | - | SP |
| usedCars Filtro de carros usados para Webmotors PLP. Pelo menos um entre usedCars/newCars deve ser true. | boolean | Opcional | Opcional; deve manter ao menos um entre usedCars/newCars true. | true | true |
| newCars Filtro de carros novos para Webmotors PLP. Pelo menos um entre usedCars/newCars deve ser true. | boolean | Opcional | Opcional; deve manter ao menos um entre usedCars/newCars true. | false | false |
| 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 |
Consulta por cidade e UF com pagina e flags de novo/usado.
{
"target": "webmotors.com.br",
"type": "plp",
"city": "Sao Jose dos Pinhais",
"state": "PR",
"usedCars": true,
"newCars": true,
"page": 1
}Mapa de paths de saída com tipo esperado para esta API.
{
"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.city": "string",
"data.citySlug": "string",
"data.state": "string",
"data.usedCars": "boolean",
"data.newCars": "boolean",
"data.searchMode": "string",
"data.totalResults": "number",
"data.primaryResults": "number",
"data.page": "number",
"data.resultsPerPage": "number",
"data.offset": "number",
"data.nextPage": "number",
"data.nextPageUrl": "string",
"data.availableFilters[]": "string",
"data.items[].position": "number",
"data.items[].url": "string",
"data.items[].advertisementUrl": "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[].regularPrice": "number",
"data.items[].brand.name": "string",
"data.items[].model": "string",
"data.items[].version": "string",
"data.items[].manufactureYear": "number",
"data.items[].modelYear": "number",
"data.items[].mileageKm": "number",
"data.items[].transmission": "string",
"data.items[].bodyType": "string",
"data.items[].fuelType": "string",
"data.items[].numberOfDoors": "number",
"data.items[].thumbnail": "string",
"data.items[].images[].url": "string",
"data.items[].sellerId": "string",
"data.items[].sellerName": "string",
"data.items[].sellerType": "string",
"data.items[].sellerCity": "string",
"data.items[].sellerState": "string",
"data.items[].productCode": "string",
"data.items[].channels[]": "string",
"data.items[].goodDeal": "boolean",
"data.items[].hotDeal": "boolean",
"data.items[].fipePercent": "number",
"data.items[].isInspected": "boolean",
"data.items[].isZeroKm": "boolean"
}{
"requestId": "99999999-1111-4111-8111-999999999999",
"executionId": "99999999-2222-4222-8222-999999999999",
"data": {
"source": "webmotors.com.br",
"type": "plp",
"url": "https://www.webmotors.com.br/carros/pr-sao-jose-dos-pinhais",
"requestUrl": "https://www.webmotors.com.br/api/search/car?...&actualPage=1",
"extractedAt": "2026-02-12T14:01:00.000Z",
"query": "volvo",
"city": "Sao Jose dos Pinhais",
"citySlug": "sao-jose-dos-pinhais",
"state": "PR",
"usedCars": true,
"newCars": true,
"searchMode": "all",
"totalResults": 978,
"primaryResults": 47,
"page": 1,
"resultsPerPage": 47,
"offset": 0,
"nextPage": 2,
"nextPageUrl": "https://www.webmotors.com.br/api/search/car?...&actualPage=2",
"availableFilters": [
"price",
"year",
"transmission"
],
"items": [
{
"position": 1,
"url": "https://www.webmotors.com.br/comprar/omoda/7/.../64572082",
"advertisementUrl": "https://www.webmotors.com.br/comprar/omoda/7/.../64572082",
"sku": "64572082",
"name": "OMODA 7 1.5 TGDI PHEV PRESTIGE DHT",
"condition": "used",
"currency": "BRL",
"currencyRaw": "R$",
"price": 108900,
"regularPrice": 112900,
"brand": {
"name": "OMODA"
},
"model": "7",
"version": "1.5 TGDI PHEV PRESTIGE DHT",
"manufactureYear": 2024,
"modelYear": 2025,
"mileageKm": 12000,
"transmission": "Automatica",
"bodyType": "SUV",
"fuelType": "Hibrido",
"numberOfDoors": 4,
"thumbnail": "https://www.webmotors.com.br/imagens/prod/380151/OMODA_7.webp",
"images": [
{
"url": "https://www.webmotors.com.br/imagens/prod/380151/OMODA_7.webp"
}
],
"sellerId": "8855",
"sellerName": "PRIXX",
"sellerType": "dealer",
"sellerCity": "Sao Jose dos Pinhais",
"sellerState": "PR",
"productCode": "380151",
"channels": [
"WEBMOTORS",
"MOBILE"
],
"goodDeal": false,
"hotDeal": true,
"fipePercent": 94.5,
"isInspected": true,
"isZeroKm": false
}
]
}
}| Path | Tipo | Descrição | Exemplo |
|---|---|---|---|
| data.availableFilters[] | string | Campo data.availableFilters[] retornado no payload de resposta. | price |
| data.city | string | Campo data.city retornado no payload de resposta. | Sao Jose dos Pinhais |
| data.citySlug | string | Campo data.citySlug retornado no payload de resposta. | sao-jose-dos-pinhais |
| data.extractedAt | string (iso datetime) | Campo data.extractedAt retornado no payload de resposta. | 2026-02-12T14:01:00.000Z |
| data.items[].advertisementUrl | string | Campo data.items[].advertisementUrl retornado no payload de resposta. | https://www.webmotors.com.br/comprar/omoda/7/.../64572082 |
| data.items[].bodyType | string | Campo data.items[].bodyType retornado no payload de resposta. | SUV |
| data.items[].brand.name | string | Campo data.items[].brand.name retornado no payload de resposta. | OMODA |
| data.items[].channels[] | string | Campo data.items[].channels[] retornado no payload de resposta. | WEBMOTORS |
| data.items[].condition | string | Campo data.items[].condition retornado no payload de resposta. | used |
| 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[].fipePercent | number | Campo data.items[].fipePercent retornado no payload de resposta. | 94.5 |
| data.items[].fuelType | string | Campo data.items[].fuelType retornado no payload de resposta. | Hibrido |
| data.items[].goodDeal | boolean | Campo data.items[].goodDeal retornado no payload de resposta. | false |
| data.items[].hotDeal | boolean | Campo data.items[].hotDeal retornado no payload de resposta. | true |
| data.items[].images[].url | string | Campo data.items[].images[].url retornado no payload de resposta. | https://www.webmotors.com.br/imagens/prod/380151/OMODA_7.webp |
| data.items[].isInspected | boolean | Campo data.items[].isInspected retornado no payload de resposta. | true |
| data.items[].isZeroKm | boolean | Campo data.items[].isZeroKm retornado no payload de resposta. | false |
| data.items[].manufactureYear | number | Campo data.items[].manufactureYear retornado no payload de resposta. | 2024 |
| data.items[].mileageKm | number | Campo data.items[].mileageKm retornado no payload de resposta. | 12000 |
| data.items[].model | string | Campo data.items[].model retornado no payload de resposta. | 7 |
| data.items[].modelYear | number | Campo data.items[].modelYear retornado no payload de resposta. | 2025 |
| data.items[].name | string | Campo data.items[].name retornado no payload de resposta. | OMODA 7 1.5 TGDI PHEV PRESTIGE DHT |
| data.items[].numberOfDoors | number | Campo data.items[].numberOfDoors retornado no payload de resposta. | 4 |
| data.items[].position | number | Campo data.items[].position retornado no payload de resposta. | 1 |
| data.items[].price | number | Campo data.items[].price retornado no payload de resposta. | 108900 |
| data.items[].productCode | string | Campo data.items[].productCode retornado no payload de resposta. | 380151 |
| data.items[].regularPrice | number | Campo data.items[].regularPrice retornado no payload de resposta. | 112900 |
| data.items[].sellerCity | string | Campo data.items[].sellerCity retornado no payload de resposta. | Sao Jose dos Pinhais |
| data.items[].sellerId | string | Campo data.items[].sellerId retornado no payload de resposta. | 8855 |
| data.items[].sellerName | string | Campo data.items[].sellerName retornado no payload de resposta. | PRIXX |
| data.items[].sellerState | string | Campo data.items[].sellerState retornado no payload de resposta. | PR |
| data.items[].sellerType | string | Campo data.items[].sellerType retornado no payload de resposta. | dealer |
| data.items[].sku | string | Campo data.items[].sku retornado no payload de resposta. | 64572082 |
| data.items[].thumbnail | string | Campo data.items[].thumbnail retornado no payload de resposta. | https://www.webmotors.com.br/imagens/prod/380151/OMODA_7.webp |
| data.items[].transmission | string | Campo data.items[].transmission retornado no payload de resposta. | Automatica |
| data.items[].url | string | Campo data.items[].url retornado no payload de resposta. | https://www.webmotors.com.br/comprar/omoda/7/.../64572082 |
| data.items[].version | string | Campo data.items[].version retornado no payload de resposta. | 1.5 TGDI PHEV PRESTIGE DHT |
| data.newCars | boolean | Campo data.newCars retornado no payload de resposta. | true |
| 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.webmotors.com.br/api/search/car?...&actualPage=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. | 47 |
| data.query | string | Campo data.query retornado no payload de resposta. | volvo |
| data.requestUrl | string | Campo data.requestUrl retornado no payload de resposta. | https://www.webmotors.com.br/api/search/car?...&actualPage=1 |
| data.resultsPerPage | number | Campo data.resultsPerPage retornado no payload de resposta. | 47 |
| data.searchMode | string | Campo data.searchMode retornado no payload de resposta. | all |
| data.source | string | Campo data.source retornado no payload de resposta. | webmotors.com.br |
| data.state | string | Campo data.state retornado no payload de resposta. | PR |
| data.totalResults | number | Campo data.totalResults retornado no payload de resposta. | 978 |
| 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.webmotors.com.br/carros/pr-sao-jose-dos-pinhais |
| data.usedCars | boolean | Campo data.usedCars retornado no payload de resposta. | true |
| executionId | string (uuid) | Campo executionId retornado no payload de resposta. | 99999999-2222-4222-8222-999999999999 |
| requestId | string (uuid) | Campo requestId retornado no payload de resposta. | 99999999-1111-4111-8111-999999999999 |
| 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. |