Documentação da API

API REST para extração de dados de negócios locais do Google Maps. Base URL:

Base URL 
https://api.local-api.com

Prefixo da API: /api/v1. Todas as respostas em JSON. Desenvolvimento local em http://localhost:8000.

Quick Start

Comece a usar a API em 3 passos:

1. Faça uma busca rápida

Busca rápida 
curl "https://api.local-api.com/api/v1/search?query=Restaurantes+em+Brasilia&limit=5" \
  -H "X-API-Key: sua-api-key"

2. Crie um job assíncrono para mais resultados

Criar job assíncrono 
curl -X POST "https://api.local-api.com/api/v1/search/jobs" \
  -H "X-API-Key: sua-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hotéis em São Paulo", "limit": 50, "mode": "complete"}'

3. Consulte o status do job

Consultar status 
curl "https://api.local-api.com/api/v1/jobs/{job_id}" \
  -H "X-API-Key: sua-api-key" \
  -H "Prefer: wait=30"

Autenticação

Todos os endpoints autenticados requerem o header X-API-Key.

Header de autenticação 
X-API-Key: <sua-api-key>

Headers de Rate Limit

Presentes em todas as respostas autenticadas:

Header Descrição
X-Request-ID UUID único da requisição
X-RateLimit-Limit Limite de RPM
X-RateLimit-Remaining Requisições restantes
X-RateLimit-Reset Timestamp de reset
X-RateLimit-Daily-Limit Limite diário
X-RateLimit-Daily-Remaining Diárias restantes
X-Request-Latency-Ms Latência em ms

Rate Limiting

Cada plano possui limites de requisições por minuto (RPM) e diárias. Ao exceder qualquer limite, a API retorna status 429 com um dos códigos abaixo:

Code Descrição
RATE_LIMIT_EXCEEDED RPM excedido
DAILY_LIMIT_EXCEEDED Limite diário excedido
QUEUE_OVERLOADED Fila sobrecarregada
CONCURRENT_JOBS_LIMIT_EXCEEDED Jobs concorrentes no limite
PLAN_QUOTA_EXCEEDED Quota do plano atingida

Códigos de Erro

Código HTTP Code Descrição
401 MISSING_API_KEY Header X-API-Key ausente
403 INVALID_API_KEY API key inválida
403 TENANT_INACTIVE Tenant inativo/suspenso
403 PLAN_REQUIRES_UPGRADE Plano não permite o modo
429 (vários) Ver Rate Limiting
503 CIRCUIT_BLOCKED Circuit breaker ativado

Busca Síncrona

Jobs Assíncronos

POST /api/v1/search/jobs Auth Cria job assíncrono de scraping. Retorna job_id imediatamente.
Headers
Idempotency-Key Chave para evitar jobs duplicados
Request Body 
{"query":"Hotéis em São Paulo","limit":50,"language":"pt-BR","mode":"complete","use_cache":true,"callback_url":"https://meu-site.com/webhook","idempotency_key":"busca-hoteis-sp-2026","auto_retry_on_recovery":false}
Response 
{"job_id":"550e8400-...","status":"queued","estimated_wait_s":15,"queued":true}
GET /api/v1/jobs/{job_id} Auth Consulta status do job. Suporta long-polling via header Prefer.
Path Parameters
job_id UUID do job
Headers
Prefer wait=30 Espera até 30s por mudança de status
Response 
{"job_id":"550e8400-...","status":"completed","progress":100,"payload":{"query":"Hotéis em São Paulo","limit":50,"mode":"complete"},"result":{"status":"OK","total_results":50,"results":[...]},"error":null,"attempts":1,"created_at":"2026-02-20T10:30:00Z","completed_at":"2026-02-20T10:31:00Z","cost_cents":10}

Estados do job

Status Descrição
queued Aguardando na fila
running Em execução
completed Finalizado com sucesso
failed Falhou após tentativas
timeout Expirou
cancelled Cancelado
POST /api/v1/jobs/{job_id}/retry Auth Reenfileira job em estado terminal.
Path Parameters
job_id UUID do job
Request Body 
{"force": false}
GET /api/v1/jobs/{job_id}/stream Auth Stream SSE para acompanhamento em tempo real. Content-Type: text/event-stream.
Path Parameters
job_id UUID do job
Eventos SSE 
event: queued
data: {"job_id":"...","status":"queued","progress":0}

event: running
data: {"job_id":"...","status":"running","progress":35}

event: completed
data: {"job_id":"...","status":"completed","progress":100,"result":{...}}

Detalhes de Negócio

GET /api/v1/business/{place_id} Auth Detalhes completos de um negócio pelo place_id do Google.
Path Parameters
place_id ID do local no Google Maps
Query Parameters
Param
Tipo
Default
Descrição
mode
string
fast
fast (básico) ou complete (com popular_times, social_media)
use_cache
bool
true
Usar cache
Response 
{"place_id":"ChIJN1t_tDeu...","name":"Restaurante Exemplo","phone_number":"+55 61 3333-4444","full_address":"SQS 308 Bloco A, Brasília - DF","rating":4.5,"review_count":230,"working_hours":{"segunda-feira":["11:00–15:00","18:00–23:00"]},"popular_times":{"days":[{"day":"Segunda-feira","hours":[{"hour":12,"percentage":75}]}],"live_busyness":45},"social_media":{"facebook":"https://facebook.com/exemplo","instagram":"https://instagram.com/exemplo"}}

Cache & Webhooks

DELETE /api/v1/cache Auth Limpa cache de resultados.
Query Parameters
Param
Tipo
Default
Descrição
pattern
string
*
Padrão glob de chaves
Response 
{"cleared":42,"pattern":"lbs:*"}
POST /api/v1/webhooks/test Auth Envia callback assinado para validar endpoint. Requer feature webhook_enabled.
Request Body 
{"callback_url":"https://meu-site.com/webhook","secret":"meu-secret-opcional"}
Response 
{"sent":true,"callback_url":"https://meu-site.com/webhook"}

SDKs & Exemplos

cURL 
curl "https://api.local-api.com/api/v1/search?query=Restaurantes+em+Brasilia&limit=5" \
  -H "X-API-Key: sua-api-key"
JavaScript (fetch) 
const response = await fetch(
  "https://api.local-api.com/api/v1/search?query=Restaurantes+em+Brasilia&limit=5",
  { headers: { "X-API-Key": "sua-api-key" } }
);
const data = await response.json();
console.log(data.results);
Python (requests) 
import requests

response = requests.get(
    "https://api.local-api.com/api/v1/search",
    params={"query": "Restaurantes em Brasilia", "limit": 5},
    headers={"X-API-Key": "sua-api-key"}
)
data = response.json()
print(data["results"])