DOCUMENTACIÓN API

Construye sobre
Mapalyze.

La API REST de Mapalyze le da acceso programático a todos los registros de campo, formularios, activos y exportaciones. Úsela para integrar datos de campo en sus sistemas existentes, automatizar flujos de trabajo o construir aplicaciones personalizadas sobre nuestra plataforma.

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

REST JSON GeoJSON OAuth 2.0 Webhooks 10K req/hr

Autenticación

Todas las solicitudes a la API requieren un token Bearer en la cabecera Authorization. Genera tu clave API en el panel de Mapalyze, en Configuración → Claves API.

⚡

Mantenga su clave API en secreto. Nunca la exponga en código del lado del cliente. Si una clave se ve comprometida, revóquela inmediatamente desde el panel de control.

              # 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)

Registros

Los registros de campo son el recurso principal de la API de Mapalyze. Cada registro incluye datos del formulario, coordenadas GPS, fotos y metadatos capturados en terreno.

GET /v1/records Listar todos los registros de campo

PARÁMETRO	TIPO	OBLIGATORIO	DESCRIPCIÓN
form_id	string	opcional	Filtrar registros por ID de formulario
limit	integer	opcional	Número de registros a devolver (predeterminado: 50, máx: 500)
offset	integer	opcional	Desplazamiento de paginación
format	string	opcional	Formato de respuesta: json o geojson (predeterminado: json)
since	ISO 8601	opcional	Devolver registros creados después de esta marca de tiempo

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

                    -H "Authorization: Bearer YOUR_API_KEY"
                
RESPUESTA 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 Crear un nuevo registro de campo

PARÁMETRO DEL BODY	TIPO	OBLIGATORIO	DESCRIPCIÓN
form_id	string	obligatorio	ID del formulario a usar para este registro
coordinates	array	obligatorio	Coordenadas GeoJSON [lng, lat] o [lng, lat, alt]
data	object	obligatorio	Valores de campos del formulario como pares clave-valor
captured_at	ISO 8601	opcional	Sobrescribir marca de tiempo de captura (por defecto: ahora)

Exportaciones

Exporta tus datos de campo como GeoJSON, CSV o informes PDF. Las exportaciones de gran tamaño se generan de forma asíncrona.

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

⚡

Las exportaciones de más de 10.000 registros se procesan de forma asíncrona. La API devuelve un <strong>job_id</strong>; consulta <code>/v1/jobs/{job_id}</code> para ver el estado y obtener la URL de descarga cuando termine.

                  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

Recibe notificaciones HTTP en tiempo real cuando ocurren eventos de campo: registros creados, sincronizados o actualizados. Perfecto para disparar flujos aguas abajo en cuanto llegan los datos.

EVENTO	DESCRIPCIÓN
record.created	Se ha creado un nuevo registro de campo
record.synced	Un registro offline se ha sincronizado con el servidor
record.updated	Se ha modificado un registro existente
record.deleted	Se ha eliminado un registro
export.completed	Un trabajo de exportación asíncrona ha finalizado

Errores

Mapalyze usa códigos de estado HTTP estándar. Todos los errores devuelven un cuerpo JSON con un código y mensaje.

200

Solicitud exitosa

400

BAD REQUEST

Parámetros o cuerpo inválidos

401

UNAUTHORIZED

Clave API inválida o faltante

404

NOT FOUND

El recurso no existe

429

RATE LIMITED

Demasiadas solicitudes

500

SERVER ERROR

Algo salió mal de nuestro lado

Límites de tasa

Los límites de tasa se aplican por clave API. Exceder los límites devuelve un 429 con una cabecera Retry-After.

PLAN	SOLICITUDES / HORA	TAMAÑO DE EXPORTACIÓN
Starter	1,000	10,000 records
Pro	10,000	500,000 records
Enterprise	Ilimitado	Ilimitado

⚠

Entrega de webhook: Los webhooks se reintentan hasta 5 veces con retroceso exponencial. Los endpoints que fallan consistentemente durante 72 horas se desactivan automáticamente.

Construye sobreMapalyze.