// docs

Google Search

Extrai resultados orgânicos do Google Search por palavra-chave, com geolocalização fixa no Brasil e paginação por página.

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": "Royal Imóveis Rj",
  "target": "google.com",
  "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

google_com_plp

Auth

Bearer ou X-API-Key

google_com_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "google_com_plp",
    "arguments": {
      "keyword": "Royal Imóveis Rj",
      "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	Obrigatório	Obrigatorio. Representa a query enviada ao Google Search.	-	iphone 15 pro max
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, idp, plp, 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	Pagina da busca organica (inteiro >= 1).	1	2

Exemplos de request

Busca Google - primeira página

Fluxo recomendado; o backend monta a URL de busca automaticamente a partir da query.

Busca Google - primeira página

{
  "keyword": "Royal Imóveis Rj",
  "target": "google.com",
  "type": "plp",
  "page": 1
}

Busca Google - página 2

Busca orgânica na segunda página, mantendo geolocalização Brasil.

Busca Google - página 2

{
  "keyword": "apartamento curitiba pr",
  "target": "google.com",
  "type": "plp",
  "page": 2
}

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.displayedQuery": "string | null",
  "data.searchedQuery": "string | null",
  "data.geolocation": "string",
  "data.device": "string",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.offset": "number",
  "data.primaryResults": "number",
  "data.totalResults": "number | null",
  "data.nextPage": "number | null",
  "data.nextPageUrl": "string | null",
  "data.items[].position": "number",
  "data.items[].rank": "number | null",
  "data.items[].title": "string | null",
  "data.items[].description": "string | null",
  "data.items[].url": "string",
  "data.items[].displayedUrl": "string | null",
  "data.items[].domain": "string | null"
}

Exemplo de response

responseExample

{
  "requestId": "99999999-1111-4111-8111-999999999999",
  "executionId": "99999999-2222-4222-8222-999999999999",
  "data": {
    "source": "google.com",
    "type": "plp",
    "url": "https://www.google.com/search?q=Royal+Im%C3%B3veis+Rj",
    "requestUrl": "https://www.google.com/search?q=Royal+Im%C3%B3veis+Rj",
    "extractedAt": "2026-03-21T14:44:36Z",
    "query": "Royal Imóveis Rj",
    "displayedQuery": "Royal Imóveis Rj",
    "searchedQuery": "Royal Imóveis Rj",
    "geolocation": "BR",
    "device": "desktop",
    "page": 1,
    "resultsPerPage": 6,
    "offset": 0,
    "primaryResults": 6,
    "totalResults": 1090000,
    "nextPage": 2,
    "nextPageUrl": "https://www.google.com/search?q=Royal+Im%C3%B3veis+Rj&start=10",
    "items": [
      {
        "position": 1,
        "rank": 1,
        "title": "Royal Imóveis RJ",
        "description": "Unidade Freguesia de Jacarepaguá. Estrada dos Três Rios, 1097. - Loja G. Freguesia de Jacarepaguá. Rio de Janeiro/RJ.",
        "url": "https://www.royalimoveisrj.com.br/",
        "displayedUrl": "https://www.royalimoveisrj.com.br",
        "domain": "royalimoveisrj.com.br"
      },
      {
        "position": 2,
        "rank": 2,
        "title": "Royal Imóveis RJ (@royalimoveisrj)",
        "description": "6.1K+ followers · 918 posts · Imobiliária ⭐ A mais avaliada no Google Compra, Venda, Locação e Administração de imóveis Freguesia - JPA Creci J- ...",
        "url": "https://www.instagram.com/royalimoveisrj/",
        "displayedUrl": "Mais de 6,1 mil seguidores",
        "domain": "instagram.com"
      },
      {
        "position": 3,
        "rank": 3,
        "title": "Royal Imóveis Rj",
        "description": "Somos a imobiliária que é a cara de Jacarepaguá. Atuamos de forma única, envolvendo compra, venda e avaliação de imóveis residenciais. A Royal Imóveis RJ ...",
        "url": "https://www.zapimoveis.com.br/imobiliaria/655356/",
        "displayedUrl": "https://www.zapimoveis.com.br › imobiliaria",
        "domain": "zapimoveis.com.br"
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.device	string	Campo data.device retornado no payload de resposta.	desktop
data.displayedQuery	string \| null	Campo data.displayedQuery retornado no payload de resposta.	Royal Imóveis Rj
data.extractedAt	string (iso datetime)	Campo data.extractedAt retornado no payload de resposta.	2026-03-21T14:44:36Z
data.geolocation	string	Campo data.geolocation retornado no payload de resposta.	BR
data.items[].description	string \| null	Campo data.items[].description retornado no payload de resposta.	Unidade Freguesia de Jacarepaguá. Estrada dos Três Rios, 1097. - Loja G. Freguesia de Jacarepaguá. Rio de Janeiro/RJ.
data.items[].displayedUrl	string \| null	Campo data.items[].displayedUrl retornado no payload de resposta.	https://www.royalimoveisrj.com.br
data.items[].domain	string \| null	Campo data.items[].domain retornado no payload de resposta.	royalimoveisrj.com.br
data.items[].position	number	Campo data.items[].position retornado no payload de resposta.	1
data.items[].rank	number \| null	Campo data.items[].rank retornado no payload de resposta.	1
data.items[].title	string \| null	Campo data.items[].title retornado no payload de resposta.	Royal Imóveis RJ
data.items[].url	string	Campo data.items[].url retornado no payload de resposta.	https://www.royalimoveisrj.com.br/
data.nextPage	number \| null	Campo data.nextPage retornado no payload de resposta.	2
data.nextPageUrl	string \| null	Campo data.nextPageUrl retornado no payload de resposta.	https://www.google.com/search?q=Royal+Im%C3%B3veis+Rj&start=10
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.	6
data.query	string	Campo data.query retornado no payload de resposta.	Royal Imóveis Rj
data.requestUrl	string	Campo data.requestUrl retornado no payload de resposta.	https://www.google.com/search?q=Royal+Im%C3%B3veis+Rj
data.resultsPerPage	number	Campo data.resultsPerPage retornado no payload de resposta.	6
data.searchedQuery	string \| null	Campo data.searchedQuery retornado no payload de resposta.	Royal Imóveis Rj
data.source	string	Campo data.source retornado no payload de resposta.	google.com
data.totalResults	number \| null	Campo data.totalResults retornado no payload de resposta.	1090000
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.google.com/search?q=Royal+Im%C3%B3veis+Rj
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

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.