Démarrage rapide

Toutes les requêtes se font en HTTPS vers {{BASE}}/v1, avec un corps JSON et votre clé dans l'en-tête X-API-Key. Exemple : cinq boucles de trail de 10 km au départ d'Angers.

curl -X POST {{BASE}}/v1/routes \
  -H "X-API-Key: dplus_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 47.4739,
    "lon": -0.5516,
    "radius_km": 5,
    "terrain": "trail",
    "mode": "distance",
    "target_distance_km": 10
  }'

// Côté serveur (Node 18+) : ne jamais exposer la clé dans un navigateur
const res = await fetch("{{BASE}}/v1/routes", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DPLUS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lat: 47.4739, lon: -0.5516, radius_km: 5,
    terrain: "trail", mode: "distance", target_distance_km: 10,
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const { routes } = await res.json();
routes.forEach((r) => console.log(r.label, r.stats.distance_km, "km", r.stats.elevation_gain_m, "m D+"));

import os, httpx

res = httpx.post(
    "{{BASE}}/v1/routes",
    headers={"X-API-Key": os.environ["DPLUS_API_KEY"]},
    json={
        "lat": 47.4739, "lon": -0.5516, "radius_km": 5,
        "terrain": "trail", "mode": "distance", "target_distance_km": 10,
    },
    timeout=120,
)
res.raise_for_status()
for r in res.json()["routes"]:
    print(r["label"], r["stats"]["distance_km"], "km", r["stats"]["elevation_gain_m"], "m D+")

Quick start

All requests go over HTTPS to {{BASE}}/v1, with a JSON body and your key in the X-API-Key header. Example: five 10 km trail loops starting from Angers.

curl -X POST {{BASE}}/v1/routes \
  -H "X-API-Key: dplus_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 47.4739,
    "lon": -0.5516,
    "radius_km": 5,
    "terrain": "trail",
    "mode": "distance",
    "target_distance_km": 10
  }'

// Server side (Node 18+): never expose the key in a browser
const res = await fetch("{{BASE}}/v1/routes", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.DPLUS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lat: 47.4739, lon: -0.5516, radius_km: 5,
    terrain: "trail", mode: "distance", target_distance_km: 10,
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const { routes } = await res.json();
routes.forEach((r) => console.log(r.label, r.stats.distance_km, "km", r.stats.elevation_gain_m, "m D+"));

import os, httpx

res = httpx.post(
    "{{BASE}}/v1/routes",
    headers={"X-API-Key": os.environ["DPLUS_API_KEY"]},
    json={
        "lat": 47.4739, "lon": -0.5516, "radius_km": 5,
        "terrain": "trail", "mode": "distance", "target_distance_km": 10,
    },
    timeout=120,
)
res.raise_for_status()
for r in res.json()["routes"]:
    print(r["label"], r["stats"]["distance_km"], "km", r["stats"]["elevation_gain_m"], "m D+")

Authentification

Chaque requête porte votre clé dans l'en-tête X-API-Key. Les clés commencent par dplus_ et vous sont transmises une seule fois, à la création. Demandez la vôtre en décrivant votre projet.

Authentication

Every request carries your key in the X-API-Key header. Keys start with dplus_ and are sent to you once, when created. Request yours by describing your project.

Quotas et débit

• Deux quotas : les générations réussies de POST /v1/routes, et les conversations avec l'assistant (POST /v1/assistant), comptés séparément. Les compteurs repartent à zéro le 1^er de chaque mois (UTC) ; pour un accès de démonstration, ils valent pour toute sa durée. Les fichiers GPX et la consultation de la consommation sont hors quota.
• Débit : un nombre limité d'appels par minute et par clé. Au-delà, l'API répond 429 avec l'en-tête Retry-After.

Chaque réponse réussie indique où vous en êtes :

X-Quota-Limit: 1000
X-Quota-Remaining: 987

Quotas and rate limits

• Two quotas: successful POST /v1/routes generations, and assistant conversations (POST /v1/assistant), counted separately. Counters reset on the 1^st of each month (UTC); for a demo access, they cover its whole duration. GPX files and usage queries do not count.
• Rate limit: a limited number of calls per minute and per key. Beyond that, the API returns 429 with a Retry-After header.

Every successful response tells you where you stand:

X-Quota-Limit: 1000
X-Quota-Remaining: 987

Calcule jusqu'à cinq parcours nettement différents, classés du meilleur au moins bon. Seuls lat, lon et radius_km sont obligatoires ; l'objectif dépend de mode. Le calcul prend en général de 1 à 20 secondes, jusqu'à 40 secondes pour plus de 100 km : prévoyez un délai d'attente d'au moins 120 secondes.

Paramètres principaux

Modes

Si l'objectif est hors de portée dans la zone (par exemple 1 000 m de D+ en terrain plat), les parcours les plus proches sont tout de même renvoyés et le champ message commence par « ⚠ » avec l'explication.

Parcours avancés

Exemple : 15 km avec le plus de D+ possible et un passage imposé

{
  "lat": 47.4739, "lon": -0.5516, "radius_km": 8,
  "terrain": "trail",
  "mode": "elevation_max",
  "target_distance_km": 15,
  "steps": [
    { "action": "point", "lat": 47.4806, "lon": -0.5925, "name": "Étang Saint-Nicolas" }
  ],
  "preferences": { "near_water": true }
}

Computes up to five clearly different routes, ranked from best to worst. Only lat, lon and radius_km are required; the goal depends on mode. Computing usually takes 1 to 20 seconds, up to 40 seconds beyond 100 km: set a timeout of at least 120 seconds.

Main parameters

Modes

If the goal is out of reach in the area (for example 1,000 m of elevation gain on flat ground), the closest routes are still returned and the message field starts with “⚠” and the explanation.

Advanced routes

Example: 15 km with as much climbing as possible and a required stop

{
  "lat": 47.4739, "lon": -0.5516, "radius_km": 8,
  "terrain": "trail",
  "mode": "elevation_max",
  "target_distance_km": 15,
  "steps": [
    { "action": "point", "lat": 47.4806, "lon": -0.5925, "name": "Étang Saint-Nicolas" }
  ],
  "preferences": { "near_water": true }
}

Format de la réponse

La réponse contient la liste routes (cinq au plus, parfois moins si la zone n'offre pas assez de parcours vraiment différents) et un message de synthèse.

{
  "routes": [
    {
      "rank": 1,
      "label": "Itinéraire 1 — Meilleur",
      "color": "#dc2626",
      "geojson": { "type": "FeatureCollection", "features": [
        { "type": "Feature", "geometry": { "type": "LineString",
          "coordinates": [[-0.551629, 47.473894, 22.1], …] } } ] },
      "stats": { "distance_km": 10.44, "elevation_gain_m": 81.9, "elevation_loss_m": 80.4 },
      "elevation_profile": [{ "distance_m": 0.0, "elevation_m": 22.1 }, …],
      "message": "Direction NE · 42 % chemins / sentiers · 36 % au bord de l'eau",
      "route_start_lat": 47.473894, "route_start_lon": -0.551629,
      "laps": [],
      "directions": {
        "forward": { "elevation_gain_m": 81.9, "max_grade_pct": 5.7, "longest_climb_m": 3240, "biggest_climb_m": 32.7, … },
        "reverse": { "elevation_gain_m": 75.4, "max_grade_pct": 6.8, … }
      },
      "one_way": false
    }
  ],
  "mode": "distance",
  "message": "…"
}

Response format

The response contains the routes list (five at most, sometimes fewer when the area does not offer enough truly different routes) and a summary message.

{
  "routes": [
    {
      "rank": 1,
      "label": "Route 1 — Best",
      "color": "#dc2626",
      "geojson": { "type": "FeatureCollection", "features": [
        { "type": "Feature", "geometry": { "type": "LineString",
          "coordinates": [[-0.551629, 47.473894, 22.1], …] } } ] },
      "stats": { "distance_km": 10.44, "elevation_gain_m": 81.9, "elevation_loss_m": 80.4 },
      "elevation_profile": [{ "distance_m": 0.0, "elevation_m": 22.1 }, …],
      "message": "Heading NE · 42% paths and trails · 36% along water",
      "route_start_lat": 47.473894, "route_start_lon": -0.551629,
      "laps": [],
      "directions": {
        "forward": { "elevation_gain_m": 81.9, "max_grade_pct": 5.7, "longest_climb_m": 3240, "biggest_climb_m": 32.7, … },
        "reverse": { "elevation_gain_m": 75.4, "max_grade_pct": 6.8, … }
      },
      "one_way": false
    }
  ],
  "mode": "distance",
  "message": "…"
}

Transforme un tracé en fichier GPX 1.1, à importer dans une montre ou une application de course. Hors quota.

curl -X POST {{BASE}}/v1/gpx \
  -H "X-API-Key: dplus_votre_cle" -H "Content-Type: application/json" \
  -d '{"name": "Boucle du lac", "coordinates": [[-0.5516, 47.4739, 22.1], [-0.5525, 47.4737, 20.7]]}' \
  -o parcours.gpx

coordinates reprend directement geojson.features[0].geometry.coordinates (2 à 50 000 points). name (120 caractères) et description (500 caractères) sont facultatifs.

Turns a route into a GPX 1.1 file, to import into a watch or running app. Does not count towards the quota.

curl -X POST {{BASE}}/v1/gpx \
  -H "X-API-Key: dplus_votre_cle" -H "Content-Type: application/json" \
  -d '{"name": "Lake loop", "coordinates": [[-0.5516, 47.4739, 22.1], [-0.5525, 47.4737, 20.7]]}' \
  -o route.gpx

coordinates is simply geojson.features[0].geometry.coordinates (2 to 50,000 points). name (120 characters) and description (500 characters) are optional.

Un message en langage naturel à l'assistant IA, qui le traduit en parcours calculés sur la carte. Disponible si l'assistant est inclus dans votre accès ; chaque conversation compte une fois dans votre quota, à son premier message abouti ; les messages suivants de la même conversation (session_id) sont inclus, dans la limite de 12.

• Premier message : message, context (mêmes champs que /v1/routes : départ, rayon, terrain, objectif éventuel) et place (nom du départ).
• Messages suivants : message et le session_id de la réponse précédente (« plus court », « moins de route »). Une conversation expire après 2 heures sans message.
• Réponse : soit des parcours dans routes (même format que /v1/routes) avec un texte reply, soit une question à poser à votre utilisateur, avec des options de réponse.

curl -X POST {{BASE}}/v1/assistant \
  -H "X-API-Key: dplus_votre_cle" -H "Content-Type: application/json" \
  -d '{
    "message": "Deux fois le tour du lac de Maine",
    "place": "Angers",
    "context": { "lat": 47.4739, "lon": -0.5516, "radius_km": 8, "terrain": "trail",
                 "mode": "distance", "target_distance_km": 12 }
  }'

{
  "session_id": "9f2c…",
  "reply": "Voici deux tours du lac de Maine…",
  "question": null,
  "options": [],
  "routes": { "routes": [ … ] }
}

Les en-têtes X-Assistant-Quota-Limit et X-Assistant-Quota-Remaining indiquent où vous en êtes. Prévoyez un délai d'attente de 180 secondes : l'assistant enchaîne plusieurs calculs.

A plain-language message to the AI assistant, which turns it into routes computed on the map. Available when the assistant is included in your access; each conversation counts once towards your quota, on its first successful message; follow-up messages in the same conversation (session_id) are included, up to 12.

• First message: message, context (same fields as /v1/routes: start, radius, terrain, optional goal) and place (name of the start).
• Follow-up messages: message and the session_id from the previous response (“shorter”, “less road”). A conversation expires after 2 hours without a message.
• Response: either routes in routes (same format as /v1/routes) with a reply text, or a question to ask your user, with answer options.

curl -X POST {{BASE}}/v1/assistant \
  -H "X-API-Key: dplus_votre_cle" -H "Content-Type: application/json" \
  -d '{
    "message": "Twice around Lac de Maine",
    "place": "Angers",
    "context": { "lat": 47.4739, "lon": -0.5516, "radius_km": 8, "terrain": "trail",
                 "mode": "distance", "target_distance_km": 12 }
  }'

{
  "session_id": "9f2c…",
  "reply": "Here are two laps of Lac de Maine…",
  "question": null,
  "options": [],
  "routes": { "routes": [ … ] }
}

The X-Assistant-Quota-Limit and X-Assistant-Quota-Remaining headers tell you where you stand. Set a timeout of 180 seconds: the assistant chains several computations. Send Accept-Language: en to get answers in English.

Vos deux quotas, ce qu'il en reste (routes et assistant), la date de fin d'un accès de démonstration (expires_on) et le détail par jour sur les 31 derniers jours.

{
  "client": "Mon application",
  "monthly_quota": 1000,
  "used_this_month": 13,
  "remaining": 987,
  "daily": [ … ]
}

Your two quotas, what is left of them (routes and assistant), the end date of a demo access (expires_on) and a daily breakdown over the last 31 days.

{
  "client": "My app",
  "monthly_quota": 1000,
  "used_this_month": 13,
  "remaining": 987,
  "daily": [ … ]
}

Erreurs

En cas d'erreur, le corps JSON contient un champ detail qui l'explique (en anglais avec l'en-tête Accept-Language: en) ; pour les codes 422, il peut être affiché tel quel à vos utilisateurs.

Les générations en erreur ne sont pas décomptées du quota.

Errors

On error, the JSON body contains a detail field explaining it (in English with the Accept-Language: en header); for 422 codes you can show it to your users as is.

Failed generations do not count towards the quota.

Couverture et limites

• Zone couverte : France métropolitaine. Un point hors de la zone renvoie une erreur 422 explicite.
• Distance : de 1 à 200 km ; dénivelé visé : de 50 à 10 000 m ; rayon : de 1 à 30 km.
• Terrain : une préférence, pas un filtre. Un parcours « route » en pleine forêt ou « trail » en centre-ville emprunte le meilleur réseau disponible ; le message indique la part de chemins obtenue.
• Dénivelé : calculé sur le modèle de relief de l'IGN. Il peut différer de 10 à 20 % de celui mesuré par une montre à altimètre barométrique.
• Langue : messages et erreurs en français par défaut, en anglais avec l'en-tête Accept-Language: en.

Coverage and limits

• Coverage: mainland France. A point outside the area returns an explicit 422 error.
• Distance: 1 to 200 km; target elevation gain: 50 to 10,000 m; radius: 1 to 30 km.
• Terrain: a preference, not a filter. A “road” route deep in a forest or a “trail” route in a city centre uses the best network available; message gives the resulting share of paths.
• Elevation gain: computed on the IGN terrain model. It may differ by 10 to 20% from what a watch with a barometric altimeter measures.
• Language: messages and errors are in French by default, in English with the Accept-Language: en header.

Bonnes pratiques

• Appelez l'API depuis votre serveur, jamais directement depuis l'application de vos utilisateurs.
• Gardez en cache les parcours déjà calculés pour un même départ et un même objectif : ils ne changent pas d'un appel à l'autre.
• Pour proposer « d'autres parcours », renvoyez la même requête avec variant incrémenté et les tracés déjà affichés dans exclude_routes.
• Affichez l'attribution « © contributeurs OpenStreetMap » à côté des parcours (licence ODbL des données cartographiques).
• Le schéma complet est disponible au format OpenAPI : documentation interactive.

Best practices

• Call the API from your server, never directly from your users' app.
• Cache routes already computed for the same start and goal: they do not change from one call to the next.
• To offer “more routes”, send the same request again with variant incremented and the routes already shown in exclude_routes.
• Show the “© OpenStreetMap contributors” attribution next to the routes (ODbL licence of the map data).
• The full schema is available in OpenAPI format: interactive documentation.