DOCUMENTATION API

Développez sur
Mapalyze.

L'API REST de Mapalyze vous donne un accès programmatique à tous les enregistrements terrain, formulaires, actifs et exportations. Utilisez-la pour intégrer les données terrain dans vos systèmes existants, automatiser les flux de travail ou créer des applications personnalisées sur notre plateforme.

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

REST JSON GeoJSON OAuth 2.0 Webhooks 10K req/hr

Authentification

Toutes les requêtes API nécessitent un jeton Bearer transmis dans l’en-tête Authorization. Générez votre clé API dans le tableau de bord Mapalyze, via Paramètres → Clés API.

⚡

Gardez votre clé API secrète. Ne l'exposez jamais dans du code côté client. Si une clé est compromise, révoquez-la immédiatement depuis le tableau de bord.

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

Enregistrements

Les enregistrements terrain sont la ressource centrale de l’API Mapalyze. Chaque enregistrement contient les données du formulaire, les coordonnées GPS, les photos et les métadonnées capturées sur le terrain.

GET /v1/records Lister tous les enregistrements de terrain

PARAMÈTRE	TYPE	OBLIGATOIRE	DESCRIPTION
form_id	string	optionnel	Filtrer les enregistrements par ID de formulaire
limit	integer	optionnel	Nombre de fiches à retourner (par défaut : 50, max : 500)
offset	integer	optionnel	Décalage de pagination
format	string	optionnel	Format de réponse : json ou geojson (défaut : json)
since	ISO 8601	optionnel	Retourner les enregistrements créés après cet horodatage

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

                    -H "Authorization: Bearer YOUR_API_KEY"
                
RÉPONSE 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 Créer un nouvel enregistrement de terrain

PARAMÈTRE DU CORPS	TYPE	OBLIGATOIRE	DESCRIPTION
form_id	string	obligatoire	ID du formulaire à utiliser pour cet enregistrement
coordinates	array	obligatoire	Coordonnées GeoJSON [lng, lat] ou [lng, lat, alt]
data	object	obligatoire	Valeurs des champs du formulaire en paires clé-valeur
captured_at	ISO 8601	optionnel	Remplacer l'horodatage de saisie (défaut : maintenant)

Exports

Exportez vos données terrain en GeoJSON, CSV ou rapport PDF. Les gros exports sont générés de manière asynchrone.

GET /v1/export/geojson Exporter les enregistrements en GeoJSON FeatureCollection

⚡

Les exports de plus de 10 000 enregistrements sont traités de manière asynchrone. L’API renvoie un <strong>job_id</strong> ; interrogez <code>/v1/jobs/{job_id}</code> pour suivre le statut et récupérer l’URL de téléchargement une fois le traitement terminé.

                  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

Recevez des notifications HTTP en temps réel quand des événements terrain se produisent : enregistrements créés, synchronisés ou mis à jour. Parfait pour déclencher des workflows aval dès l’arrivée des données.

ÉVÉNEMENT	DESCRIPTION
record.created	Un nouvel enregistrement de terrain a été créé
record.synced	Un enregistrement hors ligne a été synchronisé avec le serveur
record.updated	Un enregistrement existant a été modifié
record.deleted	Un enregistrement a été supprimé
export.completed	Un exportation asynchrone est terminé

Erreurs

Mapalyze utilise les codes de statut HTTP standard. Toutes les erreurs retournent un corps JSON avec un code et un message.

200

Requête réussie

400

BAD REQUEST

Paramètres ou corps invalides

401

UNAUTHORIZED

Clé API invalide ou manquante

404

NOT FOUND

La ressource n'existe pas

429

RATE LIMITED

Trop de requêtes

500

SERVER ERROR

Une erreur s'est produite de notre côté

Limites de débit

Les limites de débit sont appliquées par clé API. En cas de dépassement, un code 429 avec un en-tête Retry-After est retourné.

OFFRE	REQUÊTES / HEURE	TAILLE D’EXPORT
Starter	1,000	10,000 records
Pro	10,000	500,000 records
Enterprise	Illimité	Illimité

⚠

Livraison des webhooks : Les webhooks sont relancés jusqu'à 5 fois avec un recul exponentiel. Les endpoints qui échouent de manière persistante pendant 72 heures sont automatiquement désactivés.

Développez surMapalyze.