// docs

Google Places

Extrai locais do Google Maps por palavra-chave e endereço de referência.

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 '{
  "keyword": "coffee",
  "address": "Rua XV de Novembro, 160, Curitiba, PR",
  "target": "google.com",
  "type": "places"
}'

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)	Opcional	Opcional; quando ausente o gateway monta a URL de busca canônica.	-	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	Obrigatório	Obrigatorio para definir o tipo de local pesquisado.	-	iphone 15 pro max
address Endereço de referência usado pelo Google Places para localizar a área da busca.	string	Obrigatório	Obrigatorio para definir a area de busca no Google Maps.	-	Rua XV de Novembro, 160, Curitiba, PR
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser google.com.	-	mercadolivre.com.br
type Tipo da extração: pdp, plp, review ou places.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser places.	-	pdp

Exemplos de request

Places por keyword + address

Fluxo recomendado; o gateway monta a URL canônica automaticamente.

Places por keyword + address

{
  "keyword": "coffee",
  "address": "Rua XV de Novembro, 160, Curitiba, PR",
  "target": "google.com",
  "type": "places"
}

Places com URL opcional

A URL pode ser enviada para rastreabilidade, mantendo keyword e address obrigatórios.

Places com URL opcional

{
  "url": "https://www.google.com/maps/search/?api=1&query=coffee+curitiba+pr",
  "keyword": "coffee",
  "address": "Rua XV de Novembro, 160, Curitiba, PR",
  "target": "google.com",
  "type": "places"
}

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.searchAreaUrl": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.keyword": "string",
  "data.address": "string",
  "data.searchRadiusMeters": "number",
  "data.center.latitude": "number",
  "data.center.longitude": "number",
  "data.totalResults": "number",
  "data.items[].id": "string",
  "data.items[].placeId": "string",
  "data.items[].url": "string",
  "data.items[].name": "string",
  "data.items[].address": "string",
  "data.items[].website": "string",
  "data.items[].domain": "string",
  "data.items[].phone": "string",
  "data.items[].city": "string",
  "data.items[].country": "string",
  "data.items[].plusCode": "string",
  "data.items[].latitude": "number",
  "data.items[].longitude": "number",
  "data.items[].reviewScore": "number",
  "data.items[].reviewCount": "number",
  "data.items[].categories[]": "string",
  "data.items[].price": "string"
}

Exemplo de response

responseExample

{
  "requestId": "77777777-1111-4111-8111-777777777777",
  "executionId": "77777777-2222-4222-8222-777777777777",
  "data": {
    "source": "google.com",
    "type": "places",
    "url": "https://www.google.com/maps/search/?api=1&query=coffee+Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR",
    "searchAreaUrl": "https://www.google.com/search?tbm=map&hl=en&gl=us&q=Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR",
    "requestUrl": "https://www.google.com/search?tbm=map&hl=en&gl=us&q=coffee&pb=!4m...",
    "extractedAt": "2026-02-17T20:10:00.000Z",
    "keyword": "coffee",
    "address": "Rua XV de Novembro, 160, Curitiba, PR",
    "searchRadiusMeters": 23420.81,
    "center": {
      "latitude": -25.4314,
      "longitude": -49.2721
    },
    "totalResults": 2,
    "items": [
      {
        "id": "0x94dce444ecd9879d:0xb967f191d1ba09ae",
        "placeId": "ChIJnYfZ7ETk3JQRrgm60ZHxZ7k",
        "url": "https://www.google.com/maps?cid=13363945260079319470",
        "name": "Le Caffes Especiais",
        "address": "Av. Sete de Setembro, 1865 - Centro, Curitiba - PR, 80060-070, Brazil",
        "website": "https://www.lecaffes.com.br/",
        "domain": "www.lecaffes.com.br",
        "phone": "+55 41 99999-9999",
        "city": "Curitiba",
        "country": "Brazil",
        "plusCode": "CWC8+R2",
        "latitude": -25.4348,
        "longitude": -49.2569,
        "reviewScore": 4.9,
        "reviewCount": 154,
        "categories": [
          "Coffee shop",
          "Cafe"
        ],
        "price": "$$"
      },
      {
        "id": "0x94dce5a3b5597ef7:0x929e384097106510",
        "placeId": "ChIJ9345taPl3JQREGUQl0A4npI",
        "url": "https://www.google.com/maps?cid=10569206864830616848",
        "name": "Space Cat Coffee",
        "address": "R. Dr. Generoso Borges, 365 - Batel, Curitiba - PR, 80410-010, Brazil",
        "website": "https://spacecatcoffee.com.br/",
        "domain": "spacecatcoffee.com.br",
        "phone": "+55 41 98888-8888",
        "city": "Curitiba",
        "country": "Brazil",
        "plusCode": "CWG5+6V",
        "latitude": -25.4399,
        "longitude": -49.2852,
        "reviewScore": 4.8,
        "reviewCount": 231,
        "categories": [
          "Coffee shop"
        ],
        "price": "$$"
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.address	string	Campo data.address retornado no payload de resposta.	Rua XV de Novembro, 160, Curitiba, PR
data.center.latitude	number	Campo data.center.latitude retornado no payload de resposta.	-25.4314
data.center.longitude	number	Campo data.center.longitude retornado no payload de resposta.	-49.2721
data.extractedAt	string (iso datetime)	Campo data.extractedAt retornado no payload de resposta.	2026-02-17T20:10:00.000Z
data.items[].address	string	Campo data.items[].address retornado no payload de resposta.	Av. Sete de Setembro, 1865 - Centro, Curitiba - PR, 80060-070, Brazil
data.items[].categories[]	string	Campo data.items[].categories[] retornado no payload de resposta.	Coffee shop
data.items[].city	string	Campo data.items[].city retornado no payload de resposta.	Curitiba
data.items[].country	string	Campo data.items[].country retornado no payload de resposta.	Brazil
data.items[].domain	string	Campo data.items[].domain retornado no payload de resposta.	www.lecaffes.com.br
data.items[].id	string	Campo data.items[].id retornado no payload de resposta.	0x94dce444ecd9879d:0xb967f191d1ba09ae
data.items[].latitude	number	Campo data.items[].latitude retornado no payload de resposta.	-25.4348
data.items[].longitude	number	Campo data.items[].longitude retornado no payload de resposta.	-49.2569
data.items[].name	string	Campo data.items[].name retornado no payload de resposta.	Le Caffes Especiais
data.items[].phone	string	Campo data.items[].phone retornado no payload de resposta.	+55 41 99999-9999
data.items[].placeId	string	Campo data.items[].placeId retornado no payload de resposta.	ChIJnYfZ7ETk3JQRrgm60ZHxZ7k
data.items[].plusCode	string	Campo data.items[].plusCode retornado no payload de resposta.	CWC8+R2
data.items[].price	string	Campo data.items[].price retornado no payload de resposta.	$$
data.items[].reviewCount	number	Campo data.items[].reviewCount retornado no payload de resposta.	154
data.items[].reviewScore	number	Campo data.items[].reviewScore retornado no payload de resposta.	4.9
data.items[].url	string	Campo data.items[].url retornado no payload de resposta.	https://www.google.com/maps?cid=13363945260079319470
data.items[].website	string	Campo data.items[].website retornado no payload de resposta.	https://www.lecaffes.com.br/
data.keyword	string	Campo data.keyword retornado no payload de resposta.	coffee
data.requestUrl	string	Campo data.requestUrl retornado no payload de resposta.	https://www.google.com/search?tbm=map&hl=en&gl=us&q=coffee&pb=!4m...
data.searchAreaUrl	string	Campo data.searchAreaUrl retornado no payload de resposta.	https://www.google.com/search?tbm=map&hl=en&gl=us&q=Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR
data.searchRadiusMeters	number	Campo data.searchRadiusMeters retornado no payload de resposta.	23420.81
data.source	string	Campo data.source retornado no payload de resposta.	google.com
data.totalResults	number	Campo data.totalResults retornado no payload de resposta.	2
data.type	string	Campo data.type retornado no payload de resposta.	places
data.url	string	Campo data.url retornado no payload de resposta.	https://www.google.com/maps/search/?api=1&query=coffee+Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR
executionId	string (uuid)	Campo executionId retornado no payload de resposta.	77777777-2222-4222-8222-777777777777
requestId	string (uuid)	Campo requestId retornado no payload de resposta.	77777777-1111-4111-8111-777777777777

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.
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.