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

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

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 201json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "device_track_id": "track_2024_001"
}

Envoyer des points GPS

POST/tracks/:id/points

Envoie un batch de points GPS. Jusqu'à 10 000 points par requête. Fire-and-forget (réponse 204).

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

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 204 No Content — les points sont traités de manière asynchrone.

Mettre à jour une activité

PATCH/tracks/:id

Met à 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

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"}'

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

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

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 points GPS

GET/tracks/:id/points

Retourne tous les points GPS d'une activité, triés par timestamp croissant.

Paramètres de requête

Param	Type	Required	Description
limit	integer	optional	Nombre max de points (défaut: tous, max: 50 000)
offset	integer	optional	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"

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
    }
  ]
}

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 id

Envoyer les points en batch

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

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.