DOCUMENTAÇÃO API

Construa com
Mapalyze.

A API REST do Mapalyze dá-lhe acesso programático a todos os registos de campo, formulários, ativos e exportações. Use-a para integrar dados de campo nos seus sistemas existentes, automatizar fluxos de trabalho ou construir aplicações personalizadas sobre a nossa plataforma.

URL Base https://api.mapalyze.io/v1

REST JSON GeoJSON OAuth 2.0 Webhooks 10K req/hr

Autenticacao

Todos os pedidos à API exigem um token Bearer passado no cabeçalho Authorization. Gere a sua chave API no painel do Mapalyze em Definições → Chaves API.

⚡

Mantenha a sua chave API em segredo. Nunca a exponha em código do lado do cliente. Se uma chave for comprometida, revogue-a imediatamente a partir do painel de controlo.

              # Pass your API key as a Bearer token

              curl https://api.mapalyze.io/v1/records \

                -H "Authorization: Bearer YOUR_API_KEY" \

                -H "Content-Type: application/json"
            
              const response = await fetch('https://api.mapalyze.io/v1/records', {

                headers: {

                  'Authorization': `Bearer ${API_KEY}`,

                  'Content-Type': 'application/json'

                }

              });
            
              import requests

              headers = {

                'Authorization': f'Bearer {API_KEY}',

                'Content-Type': 'application/json'

              }

              response = requests.get('https://api.mapalyze.io/v1/records', headers=headers)

Registos

Os registos de campo são o recurso central da API do Mapalyze. Cada registo contém dados do formulário, coordenadas GPS, fotos e metadados capturados no terreno.

GET /v1/records Listar todos os registos de campo

PARÂMETRO	TIPO	OBRIGATÓRIO	DESCRIÇÃO
form_id	string	opcional	Filtrar registos por ID de formulário
limit	integer	opcional	Número de registos a devolver (padrão: 50, máx.: 500)
offset	integer	opcional	Deslocamento de paginação
format	string	opcional	Formato de resposta: json ou geojson (predefinido: json)
since	ISO 8601	opcional	Devolver registos criados após esta marca temporal

                  curl 'https://api.mapalyze.io/v1/records?format=geojson&limit=10' \

                    -H "Authorization: Bearer YOUR_API_KEY"
                
RESPOSTA 200

                    {
"type": "FeatureCollection",
"total": 847,
"features": [

                        {
"type": "Feature",
"id": "rec_4Ks92mPq",
"geometry": {
"type": "Point",
"coordinates": [-0.1278, 51.5074]

                          },
"properties": {
"form_id": "form_GridInspection",
"operator": "J. Martinez",
"captured_at": "2025-03-14T09:22:11Z",
"gps_accuracy_m": 0.8,
"synced": true,
"photos": ["ph_a1b2", "ph_c3d4"]

                          }

                        }

                      ]

                    }
                  

POST /v1/records Create a new field record

PARÂMETRO DO CORPO	TIPO	OBRIGATÓRIO	DESCRIÇÃO
form_id	string	obrigatório	ID do formulário a usar para este registo
coordinates	array	obrigatório	GeoJSON coordinates [lng, lat] or [lng, lat, alt]
data	object	obrigatório	Valores dos campos do formulário como pares chave-valor
captured_at	ISO 8601	opcional	Substituir marca temporal de captura (predefinido: agora)

Exportacoes

Exporte os seus dados de campo como GeoJSON, CSV ou relatório PDF. As exportações grandes são geradas de forma assíncrona.

GET /v1/export/geojson Exportar registos como GeoJSON FeatureCollection

⚡

Exportações com mais de 10.000 registos são processadas de forma assíncrona. A API devolve um <strong>job_id</strong>; consulte <code>/v1/jobs/{job_id}</code> para ver o estado e obter o URL de descarga quando terminar.

                  curl 'https://api.mapalyze.io/v1/export/geojson?form_id=form_GridInspection&since=2025-01-01' \

                    -H "Authorization: Bearer YOUR_API_KEY" \

                    -o field_data.geojson
                
                  const res = await fetch(

                    'https://api.mapalyze.io/v1/export/geojson?form_id=form_GridInspection',

                    { headers: { 'Authorization': `Bearer ${API_KEY}` } }

                  );

                  const geojson = await res.json();

                  // Drop straight into ArcGIS, QGIS, or Mapbox

Webhooks

Receba notificações HTTP em tempo real quando ocorrem eventos de campo — registos criados, sincronizados ou atualizados. Ideal para acionar fluxos a jusante no momento em que os dados chegam.

EVENTO	DESCRICAO
record.created	A new field record has been created
record.synced	Um registo offline foi sincronizado com o servidor
record.updated	An existing record has been modified
record.deleted	Foi eliminado um registo
export.completed	Um trabalho de exportação assíncrona terminou

Erros

O Mapalyze usa codigos de status HTTP padrao. Todos os erros retornam um corpo JSON com codigo e mensagem.

200

Pedido bem-sucedido

400

BAD REQUEST

Parâmetros ou corpo inválidos

401

UNAUTHORIZED

Chave API inválida ou em falta

404

NOT FOUND

O recurso não existe

429

RATE LIMITED

Demasiados pedidos

500

SERVER ERROR

Algo correu mal do nosso lado

Rate Limits

Rate limits are applied per API key. Exceeding limits returns a 429 with a Retry-After header.

PLANO	REQUISICOES / HORA	TAMANHO DE EXPORTACAO
Starter	1,000	10,000 registos
Pro	10,000	500,000 registos
Enterprise	Ilimitado	Ilimitado

⚠

Entrega de webhook: Os webhooks são repetidos até 5 vezes com recuo exponencial. Os endpoints que falham consistentemente durante 72 horas são automaticamente desativados.

Construa comMapalyze.