Consultas Espaciais | Documentação da API Mapalyze

Consultas espaciais encontram registros por localização geográfica. Todos os endpoints espaciais usam POST com um corpo JSON e requerem no mínimo escopo read-only.

POST /v1/records/query/bbox

Encontrar registros dentro de um bounding box (retângulo no mapa).

Corpo da requisição

{
  "min_lng": -74.01,
  "min_lat": 40.70,
  "max_lng": -73.95,
  "max_lat": 40.80,
  "form_id": "frm_xyz",
  "limit": 100
}

Campo	Obrigatório	Descrição
`min_lng`	Sim	Longitude oeste
`min_lat`	Sim	Latitude sul
`max_lng`	Sim	Longitude leste
`max_lat`	Sim	Latitude norte
`form_id`	Não	Filtrar por formulário
`project_id`	Não	Filtrar por projeto
`limit`	Não	Resultados máximos (padrão 50, máx 500)

Exemplo

curl -X POST \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"min_lng": -74.01, "min_lat": 40.70, "max_lng": -73.95, "max_lat": 40.80}' \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records/query/bbox"

POST /v1/records/query/radius

Encontrar registros dentro de um raio (círculo) a partir de um ponto central.

Corpo da requisição

{
  "lng": -73.985,
  "lat": 40.758,
  "radius_meters": 500,
  "form_id": "frm_xyz"
}

Campo	Obrigatório	Descrição
`lng`	Sim	Longitude do centro
`lat`	Sim	Latitude do centro
`radius_meters`	Sim	Raio de busca em metros
`form_id`	Não	Filtrar por formulário
`project_id`	Não	Filtrar por projeto
`limit`	Não	Resultados máximos (padrão 50, máx 500)

Exemplo

curl -X POST \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"lng": -73.985, "lat": 40.758, "radius_meters": 500}' \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records/query/radius"

POST /v1/records/query/intersects

Encontrar registros que intersectam com qualquer geometria GeoJSON (polígono, linha, etc.).

Corpo da requisição

{
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-73.99, 40.75],
      [-73.98, 40.75],
      [-73.98, 40.76],
      [-73.99, 40.76],
      [-73.99, 40.75]
    ]]
  },
  "form_id": "frm_xyz"
}

Campo	Obrigatório	Descrição
`geometry`	Sim	Objeto de geometria GeoJSON
`form_id`	Não	Filtrar por formulário
`project_id`	Não	Filtrar por projeto
`limit`	Não	Resultados máximos (padrão 50, máx 500)

Exemplo: Encontrar registros em um polígono

curl -X POST \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[-73.99,40.75],[-73.98,40.75],[-73.98,40.76],[-73.99,40.76],[-73.99,40.75]]]
    }
  }' \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/records/query/intersects"

Resposta (todos os endpoints espaciais)

{
  "ok": true,
  "data": [
    {
      "id": "rec_abc123",
      "type": "record",
      "form_id": "frm_xyz",
      "properties": {"inspector_name": "Jane Smith"},
      "geometry": {"type": "Point", "coordinates": [-73.985, 40.758]},
      "created_at": "2026-02-15T14:30:00Z",
      "status": "active"
    }
  ]
}

Casos de uso

Mapas de dashboard: Carregar registros visíveis na vista atual do mapa usando bounding box
Alertas de proximidade: Encontrar inspeções dentro de 1km de uma nova ordem de serviço usando raio
Análise de zonas: Encontrar todos os registros dentro de um polígono de limite regulatório usando interseção