Documentação da API

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

Base URL 
1https://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 
1curl "https://api.local-api.com/api/v1/search?query=Restaurantes+em+Brasilia&limit=5" \
2  -H "X-API-Key: sua-api-key"

2. Crie um job assíncrono para mais resultados

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

3. Consulte o status do job

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

Autenticação

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

Header de autenticação 
1X-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": [
      {
        "place_id": "ChIJ...",
        "name": "Hotel Exemplo"
      }
    ]
  },
  "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 
1event: queued
2data: {"job_id":"...","status":"queued","progress":0}
3 
4event: running
5data: {"job_id":"...","status":"running","progress":35}
6 
7event: completed
8data: {"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 
1curl "https://api.local-api.com/api/v1/search?query=Restaurantes+em+Brasilia&limit=5" \
2  -H "X-API-Key: sua-api-key"
JavaScript (fetch) 
1const response = await fetch(
2  "https://api.local-api.com/api/v1/search?query=Restaurantes+em+Brasilia&limit=5",
3  { headers: { "X-API-Key": "sua-api-key" } }
4);
5const data = await response.json();
6console.log(data.results);
Python (requests) 
1import requests
2 
3response = requests.get(
4    "https://api.local-api.com/api/v1/search",
5    params={"query": "Restaurantes em Brasilia", "limit": 5},
6    headers={"X-API-Key": "sua-api-key"}
7)
8data = response.json()
9print(data["results"])