Documentation API
Intégrez le tracking GPS Runify dans votre application mobile. Envoyez les positions en temps réel ou synchronisez en fin de session.
Authentification
Toutes les requêtes nécessitent un token d'application transmis via le header X-API-Key.
X-API-Key: YOUR_APP_TOKEN
Le token est généré automatiquement lors de la création d'un événement dans le dashboard. Le header Authorization: Bearer est aussi accepté.
Base URL
https://api-runify.domainedunet.fr
Créer une activité
/tracksCrée une nouvelle activité GPS. Appelez cet endpoint au démarrage du tracking.
Corps de la requête
| Param | Type | Required | Description |
|---|---|---|---|
| device_track_id | string | required | Identifiant unique sur l'appareil (1–100 car.) |
| title | string | optional | Titre de l'activité (max 500 car.). Si absent, généré automatiquement : "Sortie du 12 mars à 09h20" |
| activity_type | string | optional | run | walk | bike | hike (défaut: run) |
| start_ts | ISO 8601 | optional | Date/heure de début |
| user_id | string | optional | Identifiant utilisateur (max 255 car.) |
| image_url | URL | optional | Image associée |
curl -X POST https://api-runify.domainedunet.fr/tracks \
-H "X-API-Key: YOUR_APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"device_track_id": "track_2024_001",
"title": "Morning run",
"activity_type": "run",
"start_ts": "2024-03-15T07:30:00Z"
}'Réponse 201 à la création, 200 si la même sortie est rejouée (rien n’est écrit deux fois). Le corps est ce que le serveur détient après l’écriture, pas un écho de votre requête :
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"device_track_id": "track_2024_001",
"state": "running",
"start_ts": "2024-03-15T07:30:00.000Z",
"end_ts": null,
"race_id": null,
"points_count": 0,
"last_point_ts": null,
"hidden": false,
"offered": false,
"free_credit_used": false,
"public_visible": false,
"pauses_rev": 0,
"time_basis": null,
"hero_photo_id": null,
"photos": []
}Envoyer des points GPS
/tracks/:id/pointsEnvoie un batch de points GPS. Jusqu'à 10 000 points par requête. Réponse 200 avec le décompte reçu et inséré.
Champs par point
| Param | Type | Required | Description |
|---|---|---|---|
| latitude | number | required | -90 → 90 |
| longitude | number | required | -180 → 180 |
| timestamp | ISO 8601 | required | Horodatage du point |
| altitude | number | optional | Altitude en mètres |
| accuracy | number | optional | Précision GPS en mètres |
| speed_mps | number | optional | Vitesse en m/s |
| heading | number | optional | Direction (0–360°) |
| battery | number | optional | Niveau batterie (0–1) |
| origin | string | optional | foreground | background | native |
curl -X POST https://api-runify.domainedunet.fr/tracks/TRACK_ID/points \
-H "X-API-Key: YOUR_APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"points": [
{
"latitude": 48.8566,
"longitude": 2.3522,
"altitude": 35.2,
"accuracy": 5.0,
"speed_mps": 3.2,
"timestamp": "2024-03-15T07:30:05Z",
"origin": "foreground"
},
{
"latitude": 48.8567,
"longitude": 2.3524,
"altitude": 35.5,
"timestamp": "2024-03-15T07:30:10Z"
}
]
}'{
"received": 2,
"inserted": 2,
"points_count": 128,
"last_point_ts": "2024-03-15T07:30:10.000Z"
}Mettre à jour une activité
/tracks/:idMet à jour le titre, l'état ou la date de fin d'une activité.
| Param | Type | Required | Description |
|---|---|---|---|
| title | string | optional | Nouveau titre |
| state | string | optional | running | paused | stopped |
| end_ts | ISO 8601 | optional | Date/heure de fin |
curl -X PATCH https://api-runify.domainedunet.fr/tracks/TRACK_ID \
-H "X-API-Key: YOUR_APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"state": "paused"}'Réponse 200 avec le même instantané que la création, jamais un corps vide.
Terminer une activité
/tracks/:id/finishFinalise une activité. Calcule automatiquement les statistiques (distance, allure, dénivelé…).
curl -X POST https://api-runify.domainedunet.fr/tracks/TRACK_ID/finish \ -H "X-API-Key: YOUR_APP_TOKEN"
Synchronisation complète
/syncEndpoint tout-en-un : crée l'activité, envoie les points et les statistiques en une seule requête. Idéal pour la synchronisation en fin de session. Jusqu'à 50 000 points.
Corps de la requête
| Param | Type | Required | Description |
|---|---|---|---|
| track | object | required | Objet activité (voir POST /tracks) |
| points | array | required | Tableau de points GPS |
| stats | object | optional | Statistiques pré-calculées |
Champs stats (optionnels)
| Param | Type | Required | Description |
|---|---|---|---|
| distance_meters | number | optional | Distance totale en mètres |
| duration_sec | integer | optional | Durée totale en secondes |
| elevation_gain_m | number | optional | Dénivelé positif (m) |
| elevation_loss_m | number | optional | Dénivelé négatif (m) |
| mean_speed_mps | number | optional | Vitesse moyenne (m/s) |
| pace_sec_per_km | number | optional | Allure (s/km) |
| max_speed_mps | number | optional | Vitesse max (m/s) |
| max_altitude_m | number | optional | Altitude max (m) |
| min_altitude_m | number | optional | Altitude min (m) |
| points_count | integer | optional | Nombre de points |
curl -X POST https://api-runify.domainedunet.fr/sync \
-H "X-API-Key: YOUR_APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"track": {
"device_track_id": "track_2024_001",
"title": "Trail du Glazig - 25km",
"activity_type": "run",
"start_ts": "2024-03-15T07:30:00Z",
"end_ts": "2024-03-15T09:45:00Z"
},
"points": [
{
"latitude": 48.2345,
"longitude": -3.5678,
"altitude": 45.2,
"speed_mps": 2.8,
"timestamp": "2024-03-15T07:30:05Z"
}
],
"stats": {
"distance_meters": 25340,
"duration_sec": 8100,
"elevation_gain_m": 850,
"mean_speed_mps": 3.13,
"pace_sec_per_km": 319
}
}'{
"track_id": "550e8400-e29b-41d4-a716-446655440000"
}Récupérer une activité
/tracks/:idRetourne le détail d'une activité avec ses statistiques calculées.
curl https://api-runify.domainedunet.fr/tracks/TRACK_ID \ -H "X-API-Key: YOUR_APP_TOKEN"
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"device_track_id": "track_2024_001",
"title": "Sortie du 12 mars à 09h20",
"activity_type": "run",
"state": "running",
"start_ts": "2026-03-12T09:20:00.000Z",
"end_ts": null,
"image_url": null,
"points_count": 121,
"stats": {
"distance_meters": 1200,
"duration_sec": 600,
"elevation_gain_m": 15,
"mean_speed_mps": 2.0,
"pace_sec_per_km": 500
},
"created_at": "2026-03-12T09:20:00.000Z",
"updated_at": "2026-03-12T09:30:00.000Z"
}Lister les activités d'un appareil
/tracks/mineRetourne les activités de l'appareil qui appelle, pour l'événement du token. L'appareil se prouve par l'en-tête X-Device-Id (le même device_id que celui envoyé à la création) : un autre appareil, même avec le même token, n'en reçoit aucune. Lecture seule. Les activités masquées ou verrouillées sont rendues à leur appareil ; les activités supprimées côté application le sont aussi, c'est à l'application de ne pas les ressusciter.
| Param | Type | Required | Description |
|---|---|---|---|
| limit | integer | optional | 1 à 100 (défaut : 50) |
| cursor | uuid | optional | Le next_cursor de la page précédente. L'ordre est celui de l'id, pas chronologique : triez sur start_ts. |
curl "https://api-runify.domainedunet.fr/tracks/mine?limit=50" \ -H "X-API-Key: YOUR_APP_TOKEN" \ -H "X-Device-Id: YOUR_DEVICE_ID"
{
"tracks": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"device_track_id": "your-own-track-id",
"title": "Morning run",
"activity_type": "run",
"state": "stopped",
"start_ts": "2026-03-12T09:00:00.000Z",
"end_ts": "2026-03-12T09:30:00.000Z",
"points_count": 121,
"stats": {
"distance_meters": 5200,
"duration_sec": 1800,
"elevation_gain_m": 15,
"mean_speed_mps": 2.9,
"pace_sec_per_km": 346
},
"hidden": false,
"offered": false,
"public_visible": true,
"hero_photo_id": null,
"photos": []
}
],
"next_cursor": null
}400 : X-Device-Id absent ou vide, limit hors de 1 à 100, ou cursor qui n'est pas un uuid. Pas de 404 : un appareil inconnu reçoit une liste vide (indiscernable d'un appareil sans activité). 429 avec un en-tête Retry-After au-delà de 12 appels par minute et par appareil (120 par minute et par adresse IP).
Lister les points GPS
/tracks/:id/pointsRetourne tous les points GPS d'une activité, triés par timestamp croissant. Réservé à l'appareil qui l'a créée : l'en-tête X-Device-Id doit être le device_id de l'activité. Un autre appareil, un en-tête absent et une activité inexistante reçoivent le même 404.
Paramètres de requête
| Param | Type | Required | Description |
|---|---|---|---|
| limit | integer | optional | Entier de 1 à 50 000 (défaut: tous ; au-delà de 50 000, ramené à 50 000) |
| offset | integer | optional | Entier ≥ 0, nombre de points à sauter (défaut: 0) |
curl "https://api-runify.domainedunet.fr/tracks/TRACK_ID/points?limit=1000" \ -H "X-API-Key: YOUR_APP_TOKEN" \ -H "X-Device-Id: YOUR_DEVICE_ID"
{
"track_id": "550e8400-e29b-41d4-a716-446655440000",
"count": 121,
"points": [
{
"latitude": 48.8566,
"longitude": 2.3522,
"timestamp": "2026-03-12T09:20:00.000Z",
"altitude": 35.7,
"accuracy": 5,
"speed_mps": 2.1,
"heading": 180,
"battery": 0.85
}
]
}400 : limit ou offset qui n'est pas un entier de la plage ci-dessus. 429 avec un en-tête Retry-After au-delà de 30 lectures par minute et par appareil (en-tête X-Device-Id), 300 par minute et par adresse IP.
Codes d'erreur
| Status | Code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Token manquant ou invalide |
| 400 | BAD_REQUEST | Données invalides (validation Zod) |
| 404 | NOT_FOUND | Activité introuvable |
| 409 | CONFLICT | device_track_id déjà utilisé |
| 429 | RATE_LIMIT | Trop de requêtes |
Démarrage rapide
Flux typique pour tracker une activité en temps réel :
Créer l'activité au démarrage
POST /tracks→ récupérer le idEnvoyer les points en batch
POST /tracks/:id/points→ toutes les 5–30 secondesFinaliser à la fin
POST /tracks/:id/finish→ calcule les stats automatiquement