Build on
Mapalyze.
The Mapalyze REST API gives you programmatic access to all field records, forms, assets and exports. Use it to integrate field data into your existing systems, automate workflows, or build custom applications on top of our platform.
Authentication
All API requests require a Bearer token passed in the Authorization header. Generate your API key in the Mapalyze dashboard under Settings → API Keys.
Keep your API key secret. Never expose it in client-side code. If a key is compromised, revoke it immediately from the dashboard.
curl https://api.mapalyze.io/v1/records \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
});
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
response = requests.get('https://api.mapalyze.io/v1/records', headers=headers)
Records
Field records are the core resource of the Mapalyze API. Each record contains form data, GPS coordinates, photos, and metadata captured in the field.
| PARAMETER | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| form_id | string | optional | Filter records by form ID |
| limit | integer | optional | Number of records to return (default: 50, max: 500) |
| offset | integer | optional | Pagination offset |
| format | string | optional | Response format: json or geojson (default: json) |
| since | ISO 8601 | optional | Return records created after this timestamp |
-H "Authorization: Bearer YOUR_API_KEY"
"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"]
}
}
]
}
| BODY PARAM | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| form_id | string | required | ID of the form to use for this record |
| coordinates | array | required | GeoJSON coordinates [lng, lat] or [lng, lat, alt] |
| data | object | required | Form field values as key-value pairs |
| captured_at | ISO 8601 | optional | Override capture timestamp (defaults to now) |
Exports
Export your field data as GeoJSON, CSV or PDF report. Exports are generated asynchronously for large datasets.
Exports over 10,000 records are processed asynchronously. The API returns a <strong>job_id</strong> — poll <code>/v1/jobs/{job_id}</code> for status and a download URL when complete.
-H "Authorization: Bearer YOUR_API_KEY" \
-o field_data.geojson
'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
Receive real-time HTTP notifications when field events occur — records created, synced, or updated. Perfect for triggering downstream workflows the moment data arrives from the field.
| EVENT | DESCRIPTION |
|---|---|
| record.created | A new field record has been created |
| record.synced | An offline record has synced to the server |
| record.updated | An existing record has been modified |
| record.deleted | A record has been deleted |
| export.completed | An async export job has finished |
Errors
Mapalyze uses standard HTTP status codes. All errors return a JSON body with a code and message.
Rate Limits
Rate limits are applied per API key. Exceeding limits returns a 429 with a Retry-After header.
| PLAN | REQUESTS / HOUR | EXPORT SIZE |
|---|---|---|
| Starter | 1,000 | 10,000 records |
| Pro | 10,000 | 500,000 records |
| Enterprise | Unlimited | Unlimited |
Webhook delivery: Webhooks are retried up to 5 times with exponential backoff. Endpoints that fail consistently for 72 hours are automatically disabled.