POST /v1/matrix

Vue d'ensemble

Calcule les temps de trajet et les distances entre de nombreuses origines (sources) et destinations (targets) en une seule requête. Usages typiques : affectation au dépôt le plus proche, préparation de tournées de livraison (en entrée d'un optimiseur), classements par temps de trajet (« quelle agence est la plus proche pour chaque client ? »).

Coût : 1 crédit par bloc de 25 éléments entamé, avec éléments = sources × targets (une matrice 2×3 coûte 1 crédit, une 10×10 en coûte 4). Disponibilité : à partir du plan Startup. La taille maximale de la matrice dépend de votre plan : 25×25 (625 éléments) en Startup, 50×50 (2 500) en Growth, 100×100 (10 000) en Pro.

Requête

POST https://api.geocodeme.net/v1/matrix
Content-Type: application/json

Headers requis :

• X-Api-Key: gm_YOUR_API_KEY
• Content-Type: application/json

Corps de la requête

Champ	Type	Requis	Défaut	Description
sources	array	Oui	aucun	Points d'origine au format [longitude, latitude] (1 à 100)
targets	array	Oui	aucun	Points de destination au format [longitude, latitude] (1 à 100)
profile	string	Non	car	Profil de véhicule : car, bike, foot, truck ou moto (selon le plan : bike/foot Startup+, truck/moto Growth+)
use_tolls	boolean	Non	aucun	Privilégier (true) ou éviter (false) les routes à péage. Profils motorisés uniquement
truck_height	float	Non	aucun	Hauteur du véhicule en mètres (0 à 10). Nécessite profile=truck
truck_width	float	Non	aucun	Largeur du véhicule en mètres (0 à 5). Nécessite profile=truck
truck_weight	float	Non	aucun	Poids du véhicule en tonnes (0 à 100). Nécessite profile=truck

attention

Les coordonnées sont en ordre [longitude, latitude] (standard GeoJSON), pas [lat, lon].

Exemples de code

cURL

curl -X POST \
  -H "X-Api-Key: gm_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      [2.3522, 48.8566],
      [2.2945, 48.8584]
    ],
    "targets": [
      [2.3730, 48.8443],
      [4.8357, 45.7640]
    ],
    "profile": "car"
  }' \
  "https://api.geocodeme.net/v1/matrix"

Python

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.post(
    "https://api.geocodeme.net/v1/matrix",
    json={
        "sources": [[2.3522, 48.8566], [2.2945, 48.8584]],
        "targets": [[2.3730, 48.8443], [4.8357, 45.7640]],
        "profile": "car",
    },
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
for i, row in enumerate(data["durations"]):
    for j, seconds in enumerate(row):
        if seconds is None:
            print(f"source {i} -> target {j} : pas d'itinéraire possible")
        else:
            print(f"source {i} -> target {j} : {seconds / 60:.0f} min")

JavaScript

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch("https://api.geocodeme.net/v1/matrix", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sources: [[2.3522, 48.8566], [2.2945, 48.8584]],
    targets: [[2.3730, 48.8443], [4.8357, 45.7640]],
    profile: "car",
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const data = await response.json();
data.durations.forEach((row, i) => {
  row.forEach((seconds, j) => {
    console.log(
      `source ${i} -> target ${j} : ` +
        (seconds === null ? "pas d'itinéraire" : `${Math.round(seconds / 60)} min`)
    );
  });
});

Réponse

info

Toutes les réponses incluent les headers de limitation de débit (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Monthly-Remaining, etc.).

{
  "durations": [
    [540.2, 16480.5],
    [780.9, 16890.1]
  ],
  "distances": [
    [3620.0, 465800.0],
    [5210.0, 468400.0]
  ],
  "attribution": "Route data (c) OpenStreetMap contributors",
  "meta": {
    "took_ms": 84,
    "cache_hit": false
  }
}

Schéma

Champ	Type	Description
durations	array	durations[i][j] = temps de trajet en secondes de sources[i] vers targets[j], ou null si la paire est inroutable
distances	array	distances[i][j] = distance en mètres de sources[i] vers targets[j], ou null si la paire est inroutable
attribution	string	Toujours "Route data (c) OpenStreetMap contributors"
meta.took_ms	integer	Temps de traitement serveur en millisecondes
meta.cache_hit	boolean	Indique si la réponse a été servie depuis le cache

Cellules null : paires inroutables

Un null dans durations[i][j] / distances[i][j] signifie que le moteur n'a pas pu relier cette paire source/destination. Le moteur de matrices est plus strict que /v1/route sur l'accrochage des points au réseau : un point situé dans une zone piétonne (ou loin de toute route praticable par le profil demandé) peut produire des cellules null dans une matrice alors que /v1/route trouve un itinéraire depuis ce même point. En cas de null inattendus, déplacez le point concerné vers la route ouverte à votre profil la plus proche, ou vérifiez-le d'abord avec /v1/nearest.

Réponses d'erreur

Matrice au-dessus du plafond de votre plan

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "Your plan allows up to 625 matrix elements (sources x targets). Upgrade to raise the limit.",
    "field": "sources",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

Sur le plan Free, l'endpoint lui-même n'est pas disponible ("This feature is not included in your plan. Upgrade to unlock it.").

Coordonnée invalide

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid coordinate at index 1 in 'targets' (expected [lon, lat])",
    "field": "targets"
  }
}

astuce

Tous les endpoints sont également soumis aux erreurs INVALID_API_KEY (401) et RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED (429). Consultez Codes d'erreur pour la référence complète.