Maps API

Carte, recherche d'adresses et itinéraires, à partir des données OpenStreetMap. Une API REST en JSON, une clé par application.

Adresse de base : . Toutes les requêtes sont des GET. Les coordonnées s'écrivent latitude,longitude en degrés décimaux (ex. 43.7396,7.4276) ; dans les géométries GeoJSON renvoyées, l'ordre est [longitude, latitude] comme le veut le format.

Authentification

Chaque requête porte une clé d'API, créée dans la console :

curl -H "X-Api-Key: mk_VOTRE_CLE" "/v1/geocode?q=place+du+casino"

Ou en paramètre key= (pratique pour les tuiles, chargées par la bibliothèque de carte) : /v1/tiles/14/8530/5974.pbf?key=mk_VOTRE_CLE.

Type de cléUsage
Serveur (aucun site renseigné)Appels depuis vos serveurs ou applications mobiles. À garder secrète.
Web (sites renseignés)Visible dans le code d'une page web : n'est acceptée que si la requête vient d'un des sites déclarés (en-têtes Origin / Referer).

Erreurs et limites

En cas d'erreur, la réponse contient {"error": "message"}.

CodeSignification
400Paramètre manquant ou invalide.
401Clé absente, inconnue ou révoquée.
403Clé web utilisée depuis un site non autorisé.
404Aucun résultat : point trop loin de toute route, aucun itinéraire, aucune adresse proche.
429Quota par minute de la clé dépassé : réessayer après quelques secondes.
503Service momentanément indisponible.

Limites : 25 points par itinéraire, matrice de 25 × 25, 20 résultats par recherche. Les points sont accrochés à la route la plus proche dans un rayon de 2 km.

Autocomplétion

GET/v1/autocomplete

Suggestions pendant la frappe : localités, rues, adresses et lieux d'intérêt. Le dernier mot est traité comme un début de mot, les fautes de frappe et les abréviations courantes (av, bd, st…) sont tolérées. Indiquer la position de l'utilisateur (ou le centre de la carte) favorise les résultats proches.

ParamètreDescription
q *Texte saisi (200 caractères max).
lat, lonPoint de focus (facultatif).
limitNombre de résultats, 1 à 20 (défaut 8).
typesFiltre, séparé par des virgules : place, street, address, poi.
GET /v1/autocomplete?q=bd des moul&lat=43.74&lon=7.42&limit=2

{
  "results": [
    { "id": 60, "name": "Boulevard des Moulins", "label": "Boulevard des Moulins, Monaco",
      "type": "street", "category": "secondary", "context": "Monaco",
      "lat": 43.742287, "lon": 7.4278, "score": 1.18 },
    { "id": 1119, "name": "4 Boulevard des Moulins", "label": "4 Boulevard des Moulins, Monaco",
      "type": "address", "category": "address", "context": "Monaco",
      "lat": 43.741077, "lon": 7.426484, "score": 0.98 }
  ]
}

Géocodage

GET/v1/geocode

Adresse ou nom de lieu → coordonnées. Mêmes paramètres et même réponse que l'autocomplétion (5 résultats par défaut), le meilleur résultat en premier.

GET /v1/geocode?q=Casino de Monte-Carlo&limit=1

Géocodage inverse

GET/v1/reverse?lat=…&lon=…

Coordonnées → adresse la plus proche (moins de 60 m), sinon rue la plus proche (moins de 300 m).

GET /v1/reverse?lat=43.7396&lon=7.4276

{ "result": { "id": 98, "name": "Place du Casino", "label": "Place du Casino, Monaco",
              "type": "street", "category": "service", "context": "Monaco",
              "lat": 43.739353, "lon": 7.427217, "distance_m": 17 } }

Itinéraire

GET/v1/route

Calcul d'itinéraire haute performance multi-modes (voiture, vélo, marche), avec étapes facultatives, géométrie et instructions.

ParamètreDescription
from *Départ lat,lon.
to *Arrivée lat,lon.
modeMode de déplacement : car (défaut, voiture), bike (vélo, ~15 km/h) ou walk (marche / piéton, ~4,5 km/h).
viaÉtapes dans l'ordre, séparées par | : 43.73,7.42|43.74,7.43.
langLangue des instructions : fr (défaut) ou en.
GET /v1/route?from=43.7247,7.4140&to=43.7489,7.4371

{
  "distance_m": 3737,
  "duration_s": 338,
  "legs": [ { "distance_m": 3737, "duration_s": 338 } ],
  "geometry": { "type": "LineString", "coordinates": [[7.41401, 43.72468], …] },
  "polyline": "o~liGkuel@…",
  "steps": [
    { "type": "depart", "instruction": "Partez", "name": null, "distance_m": 58, "duration_s": 7, "location": [7.41401, 43.72468] },
    { "type": "left", "instruction": "Tournez à gauche sur Avenue des Castelans", "name": "Avenue des Castelans",
      "distance_m": 179, "duration_s": 21, "location": [7.41435, 43.72502] },
    …
    { "type": "arrive", "instruction": "Vous êtes arrivé", "distance_m": 0, "duration_s": 0, "location": [7.4371, 43.7489] }
  ],
  "snapped": [ { "lat": 43.72468, "lon": 7.41401, "distance_m": 4 }, … ]
}

polyline : la même géométrie au format « encoded polyline » (précision 1e-5), compact pour les applications mobiles. type des étapes : depart, straight, slight_left, slight_right, left, right, uturn, arrive.

Matrice de distances

GET/v1/matrix

Durées et distances de chaque départ vers chaque arrivée (livraisons, recherche du plus proche…).

ParamètreDescription
sources *Départs séparés par | (25 max).
targetsArrivées (25 max) ; par défaut, les départs.
modeMode de déplacement : car (défaut), bike ou walk.
GET /v1/matrix?sources=43.7247,7.4140|43.7489,7.4371&targets=43.7310,7.4190

{ "durations_s": [[86], [307]], "distances_m": [[864], [3866]] }

Une case vaut null si aucun trajet n'existe.

Tuiles vectorielles

GET/v1/tiles/{z}/{x}/{y}.pbf

Tuiles au format Mapbox Vector Tile (zooms 4 à 20), compatibles avec MapLibre GL, OpenLayers, Leaflet (extension VectorGrid), Mapbox GL… Chaque objet porte les attributs class et, le cas échéant, name.

CoucheContenuValeurs de class
waterLacs, bassins (polygones)water
landuseOccupation du solwood, park, grass, residential, commercial, industrial, farmland, cemetery, beach, pitch
waterwayCours d'eau (lignes)river, canal, stream, drain, ditch
buildingsBâtiments (dès le zoom 13)building
roadsRoutesmotorway, trunk, primary, secondary, tertiary, residential, service… (+ _link)
pathsChemins piétons et cyclablesfootway, path, cycleway, pedestrian, track, steps
railVoies ferréesrail, subway, tram, light_rail
placesLocalités (points)city, town, village, suburb, hamlet…

Couverture

GET/v1/meta

Zone couverte (bbox, center), date des données (built_at, horodatage Unix) et statistiques. Utile pour centrer la carte au démarrage.

Lieux et commerces (POI)

GET/v1/places?bbox=west,south,east,north&limit=80

Renvoie les commerces, restaurants, écoles, pharmacies et emplacements d'une zone géographique au format standard GeoJSON FeatureCollection.

Carte sur un site web

Exemple complet avec MapLibre GL JS (libre) et une clé web :

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css">
<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
<div id="map" style="height:500px"></div>
<script>
const API = "", KEY = "mk_VOTRE_CLE_WEB";
const map = new maplibregl.Map({
  container: "map", center: [7.42, 43.74], zoom: 14,
  style: {
    version: 8,
    sources: { osm: { type: "vector", tiles: [`${API}/v1/tiles/{z}/{x}/{y}.pbf?key=${KEY}`], minzoom: 4, maxzoom: 16 } },
    layers: [
      { id: "fond", type: "background", paint: { "background-color": "#f2efe9" } },
      { id: "eau", type: "fill", source: "osm", "source-layer": "water", paint: { "fill-color": "#aad3df" } },
      { id: "batiments", type: "fill", source: "osm", "source-layer": "buildings", paint: { "fill-color": "#d9d0c9" } },
      { id: "routes", type: "line", source: "osm", "source-layer": "roads", paint: { "line-color": "#fff", "line-width": 2 } }
    ]
  }
});

// Itinéraire
fetch(`${API}/v1/route?from=43.7247,7.4140&to=43.7489,7.4371&key=${KEY}`)
  .then(r => r.json())
  .then(r => map.on("load", () => {
    map.addSource("trajet", { type: "geojson", data: r.geometry });
    map.addLayer({ id: "trajet", type: "line", source: "trajet", paint: { "line-color": "#2563eb", "line-width": 5 } });
  }));
</script>

Une démonstration complète (recherche, itinéraire, instructions) est disponible sur la page de démonstration.

Essayer

La réponse s'affichera ici.

La clé reste dans votre navigateur. Une clé web doit autoriser ce site () pour fonctionner ici.