REST API

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.

Headerhttp
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

Productiontext
https://api-runify.domainedunet.fr

Créer une activité

POST/tracks

Crée une nouvelle activité GPS. Appelez cet endpoint au démarrage du tracking.

Corps de la requête

ParamTypeRequiredDescription
device_track_idstringrequiredIdentifiant unique sur l'appareil (1–100 car.)
titlestringoptionalTitre de l'activité (max 500 car.). Si absent, généré automatiquement : "Sortie du 12 mars à 09h20"
activity_typestringoptionalrun | walk | bike | hike (défaut: run)
start_tsISO 8601optionalDate/heure de début
user_idstringoptionalIdentifiant utilisateur (max 255 car.)
image_urlURLoptionalImage associée
Exemplebash
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 :

Réponse 201json
{
  "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

POST/tracks/:id/points

Envoie 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

ParamTypeRequiredDescription
latitudenumberrequired-90 → 90
longitudenumberrequired-180 → 180
timestampISO 8601requiredHorodatage du point
altitudenumberoptionalAltitude en mètres
accuracynumberoptionalPrécision GPS en mètres
speed_mpsnumberoptionalVitesse en m/s
headingnumberoptionalDirection (0–360°)
batterynumberoptionalNiveau batterie (0–1)
originstringoptionalforeground | background | native
Exemplebash
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"
      }
    ]
  }'
💡 Réponse 200, traitement synchrone : un lot rejoué n’insère rien deux fois.
Réponse 200json
{
  "received": 2,
  "inserted": 2,
  "points_count": 128,
  "last_point_ts": "2024-03-15T07:30:10.000Z"
}

Mettre à jour une activité

PATCH/tracks/:id

Met à jour le titre, l'état ou la date de fin d'une activité.

ParamTypeRequiredDescription
titlestringoptionalNouveau titre
statestringoptionalrunning | paused | stopped
end_tsISO 8601optionalDate/heure de fin
Exemplebash
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é

POST/tracks/:id/finish

Finalise une activité. Calcule automatiquement les statistiques (distance, allure, dénivelé…).

Exemplebash
curl -X POST https://api-runify.domainedunet.fr/tracks/TRACK_ID/finish \
  -H "X-API-Key: YOUR_APP_TOKEN"

Synchronisation complète

POST/sync

Endpoint 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

ParamTypeRequiredDescription
trackobjectrequiredObjet activité (voir POST /tracks)
pointsarrayrequiredTableau de points GPS
statsobjectoptionalStatistiques pré-calculées

Champs stats (optionnels)

ParamTypeRequiredDescription
distance_metersnumberoptionalDistance totale en mètres
duration_secintegeroptionalDurée totale en secondes
elevation_gain_mnumberoptionalDénivelé positif (m)
elevation_loss_mnumberoptionalDénivelé négatif (m)
mean_speed_mpsnumberoptionalVitesse moyenne (m/s)
pace_sec_per_kmnumberoptionalAllure (s/km)
max_speed_mpsnumberoptionalVitesse max (m/s)
max_altitude_mnumberoptionalAltitude max (m)
min_altitude_mnumberoptionalAltitude min (m)
points_countintegeroptionalNombre de points
Exemplebash
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
    }
  }'
Réponse 201json
{
  "track_id": "550e8400-e29b-41d4-a716-446655440000"
}

Récupérer une activité

GET/tracks/:id

Retourne le détail d'une activité avec ses statistiques calculées.

Exemplebash
curl https://api-runify.domainedunet.fr/tracks/TRACK_ID \
  -H "X-API-Key: YOUR_APP_TOKEN"
Réponse 200json
{
  "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

GET/tracks/mine

Retourne 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.

ParamTypeRequiredDescription
limitintegeroptional1 à 100 (défaut : 50)
cursoruuidoptionalLe next_cursor de la page précédente. L'ordre est celui de l'id, pas chronologique : triez sur start_ts.
Exemplebash
curl "https://api-runify.domainedunet.fr/tracks/mine?limit=50" \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "X-Device-Id: YOUR_DEVICE_ID"
Réponse 200json
{
  "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

GET/tracks/:id/points

Retourne 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

ParamTypeRequiredDescription
limitintegeroptionalEntier de 1 à 50 000 (défaut: tous ; au-delà de 50 000, ramené à 50 000)
offsetintegeroptionalEntier ≥ 0, nombre de points à sauter (défaut: 0)
Exemplebash
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"
Réponse 200json
{
  "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

StatusCodeDescription
401UNAUTHORIZEDToken manquant ou invalide
400BAD_REQUESTDonnées invalides (validation Zod)
404NOT_FOUNDActivité introuvable
409CONFLICTdevice_track_id déjà utilisé
429RATE_LIMITTrop de requêtes

Démarrage rapide

Flux typique pour tracker une activité en temps réel :

1

Créer l'activité au démarrage

POST /tracks→ récupérer le id
2

Envoyer les points en batch

POST /tracks/:id/points→ toutes les 5–30 secondes
3

Finaliser à la fin

POST /tracks/:id/finish→ calcule les stats automatiquement
💡 Alternative : utilisez POST /sync pour tout envoyer en une seule requête à la fin de la session.