API Distance Matrix | Temps de trajet et distance

Que pouvez-vous faire avec l'API Distance Matrix ?

Pourquoi utiliser l'API Distance Matrix ?

Comment utiliser l'API Distance Matrix

Paramètres de la demande

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=<origin_location_1|origin_location_2|...|origin_location_n>&destinations=<destination_location_1|destination_location_2|...|destination_location_n>&key=<your_access_token>

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

Paramètres requis

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom&destinations=St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom&key=<your_access_token>

{
    "destination_addresses": [
        "St John's Church, North End Rd, London SW6 1PB, United Kingdom"
    ],
    "origin_addresses": [
        "Westminster Abbey, 20 Deans Yd, London SW1P 3PA, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.3 km",
                        "value": 7346
                    },
                    "duration": {
                        "text": "23 mins",
                        "value": 1401
                    },
                    "origin": "Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom",
                    "destination": "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Paramètres facultatifs

• mode (par défaut, conduite) : spécifie le mode de transport à utiliser pour calculer la distance. Les valeurs valides et les autres détails de la demande sont spécifiés dans Modes de voyage section de ce document.
• langue : langue utilisée pour renvoyer les résultats.
  
  • 
    Consultez la liste des langues prises en charge.
    
  • 
    Si la langue n'est pas fournie, l'API tente d'utiliser la langue préférée spécifiée dans l'en-tête Accept-Language, ou la langue maternelle du domaine à partir duquel la demande est envoyée.
    
  • 
    L'API fait de son mieux pour fournir une adresse postale lisible à la fois pour l'utilisateur et pour les habitants. Pour atteindre cet objectif, il renvoie les adresses postales dans la langue locale, translittérées dans un script lisible par l'utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont renvoyées dans la langue préférée. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie parmi le premier composant.
    
  • 
    Si aucun nom n'est disponible dans la langue préférée, l'API utilise la correspondance la plus proche.
    
  • 
    La langue préférée a une faible influence sur l'ensemble de résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, comme les abréviations pour les types de rues ou les synonymes qui peuvent être valides dans une langue mais pas dans une autre. Par exemple, utca et tér sont synonymes de rue en hongrois.
    

• éviter — introduit des restrictions sur l'itinéraire. Les valeurs valides sont spécifiées dans Restrictions section de ce document. Une seule restriction peut être spécifiée.
• unités : spécifie le système d'unités à utiliser pour exprimer la distance sous forme de texte. Consultez les Systèmes unitaires section de ce document pour plus d'informations.
  
• arrival_time — spécifie l'heure d'arrivée souhaitée pour les demandes de transit, en secondes depuis minuit, le 1er janvier 1970, UTC. Vous pouvez spécifier l'heure de départ ou l'heure d'arrivée, mais pas les deux. Notez que arrival_time doit être spécifié sous forme d'entier.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&arrival_time=now&transit_mode=bus&mode=transit&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "166.4 km",
                        "value": 166409
                    },
                    "duration": {
                        "text": "4 hour 2 mins",
                        "value": 14524
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• departure_time — heure de départ souhaitée. Vous pouvez spécifier l'heure sous la forme d'un entier en secondes depuis minuit, le 1er janvier 1970, UTC. Vous pouvez également spécifier la valeur now, qui définit l'heure de départ à l'heure actuelle (à la seconde près). L'heure de départ doit être réglée sur l'heure actuelle ou dans le futur. Cela ne peut pas appartenir au passé. Les résultats d'une demande donnée peuvent varier dans le temps en raison de l'évolution du réseau routier, de la mise à jour des conditions de circulation moyennes et de la nature distribuée du service. Les résultats peuvent également varier entre des itinéraires presque équivalents à tout moment et à toute fréquence. L'heure de départ peut être spécifiée dans deux cas :
  
  • 
    Pour les demandes où le mode de voyage est le transit : vous pouvez éventuellement spécifier l'une des options departure_time ou arrival_time. Si aucune heure n'est spécifiée, le departure_time est défini par défaut sur now (c'est-à-dire que l'heure de départ est par défaut l'heure actuelle).
    
  • 
    Pour les demandes concernant le mode de déplacement : vous pouvez spécifier l'heure de départ pour recevoir un itinéraire et la durée du trajet (champ de réponse : duration_in_traffic) qui tiennent compte des conditions de circulation. L'heure de départ doit être réglée sur l'heure actuelle ou dans le futur. Cela ne peut pas appartenir au passé.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• traffic_model (best_guess par défaut) : spécifie les hypothèses à utiliser pour calculer le temps passé dans le trafic. Ce paramètre affecte la valeur renvoyée dans le champ duration_in_traffic de la réponse, qui contient la durée prévue du trafic sur la base de moyennes historiques. Le paramètre traffic_model ne peut être spécifié que pour les demandes où le mode de déplacement est actif et où la demande inclut un departure_time. Les valeurs disponibles pour ce paramètre sont les suivantes :
  
  • 
    best_guess (par défaut) indique que le duration_in_traffic renvoyé doit être la meilleure estimation du temps de trajet compte tenu de ce que l'on sait des conditions de trafic historiques et du trafic réel. Le trafic en temps réel prend de l'importance à mesure que l'heure de départ se rapproche de maintenant.
    
  • 
    pessimistic indique que le duration_in_traffic renvoyé devrait être plus long que le temps de trajet réel la plupart des jours, bien que des jours occasionnels avec des conditions de circulation particulièrement mauvaises puissent dépasser cette valeur. Affecte le champ de la réponse distance_in_traffic_model, renvoyant l'itinéraire le plus court.
    
  • 
    optimistic indique que le duration_in_traffic renvoyé devrait être plus court que le temps de trajet réel la plupart des jours, bien que des jours occasionnels où les conditions de circulation soient particulièrement bonnes puissent être plus rapides que cette valeur. Affecte le champ de la réponse distance_in_traffic_model, renvoyant l'itinéraire le plus court.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&traffic_model=pessimistic&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "4 hour 0 mins",
                        "value": 14400
                    },
                    "distance_in_traffic_model": {
                        "text": "118 miles",
                        "value": 189274
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

• transit_mode — spécifie un ou plusieurs modes de transit préférés. Ce paramètre ne peut être spécifié que pour les demandes dont le mode est transit. Le paramètre prend en charge les arguments suivants :
  
  • 
    bus indique que l'itinéraire calculé doit être préféré en bus.
    
  • 
    metro indique que l'itinéraire calculé doit préférer le transport en métro.
    
  • 
    train indique que l'itinéraire calculé doit préférer le voyage en train.
    
  • 
    tram indique que l'itinéraire calculé doit privilégier les déplacements en tramway et en tramway.
    
  • 
    rail indique que l'itinéraire calculé doit être préféré en train, en tramway, en tramway et en métro. Cela équivaut à transit_mode=train|tram|subway.
    

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401&transit_mode=bus|train|tram|subway&mode=transit&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Modes de voyage

• driving (par défaut) indique le calcul de la distance à l'aide du réseau routier.
  
• la marche demande le calcul de la distance à parcourir pour marcher sur les sentiers piétonniers et les trottoirs (le cas échéant).
  
• le vélo demande le calcul de la distance à parcourir à vélo via les pistes cyclables et les rues préférées (le cas échéant).
  
• transit demande le calcul de la distance via les itinéraires de transport en commun (le cas échéant). Si vous configurez le mode de transit, vous devez spécifier une heure de départ ou une heure d'arrivée. Si aucune heure n'est spécifiée, le departure_time est défini par défaut sur now (c'est-à-dire que l'heure de départ est par défaut l'heure actuelle). Vous devez également inclure un transit_mode.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=walking&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "5.7 km",
                        "value": 5699
                    },
                    "duration": {
                        "text": "1 hour 12 mins",
                        "value": 4379
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Informations sur le trafic

• Le paramètre du mode de déplacement est la conduite, ou il n'est pas spécifié (la conduite est le mode de déplacement par défaut).
  
• La demande inclut un paramètre departure_time valide. L'heure de départ peut être réglée à l'heure actuelle ou à une autre heure.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "23 mins",
                        "value": 1395
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Restrictions

• éviter = péages
  
• éviter = autoroutes
  
• éviter = ferries
  
• éviter = intérieur
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&avoid=ferries&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Systèmes unitaires

• units=metric (par défaut) renvoie les distances en kilomètres et en mètres.
  
• units=imperial renvoie les distances en miles et en pieds.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&departure_time=now&units=imperial&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "4.7 mi",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Exemple de réponse

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Éléments de réponse de la matrice de distance

• status contient des métadonnées relatives à la demande. Voir Codes d'état ci-dessous.
  
• origin_addresses contient un tableau d'adresses tel que renvoyé par l'API à partir de votre demande d'origine. Ils sont formatés par le géocodeur et localisés en fonction du paramètre de langue transmis avec la demande.
  
• destination_addresses contient un tableau d'adresses renvoyées par l'API à partir de votre demande initiale. Comme pour les origin_addresses, celles-ci sont localisées le cas échéant.
  
• les lignes contiennent un tableau d'éléments, qui contiennent à leur tour des éléments d'état, de durée et de distance.
  

Codes d'état

Codes de statut de niveau supérieur

• OK indique que la réponse contient un résultat valide.
• INVALID_REQUEST indique que la demande fournie n'était pas valide.
• MAX_ELEMENTS_EXCEEDED indique que le produit d'origine et de destination dépasse la limite par requête.
• OVER_DAILY_LIMIT indique l'un des éléments suivants :
  
  • 
    La clé API est manquante ou non valide.
    
  • 
    La facturation n'a pas été activée sur votre compte.
    
  • 
    Le plafond d'utilisation que vous vous êtes imposé a été dépassé.
    
  • 
    Le mode de paiement fourni n'est plus valide (par exemple, une carte de crédit a expiré).
    
• OVER_QUERY_LIMIT indique que le service a reçu trop de demandes de votre application dans le délai imparti.
• REQUEST_DENIED indique que le service a refusé l'utilisation du service Distance Matrix par votre application.
• UNKNOWN_ERROR indique qu'une demande Distance Matrix n'a pas pu être traitée en raison d'une erreur du serveur. La demande peut aboutir si vous réessayez.

Codes d'état au niveau des éléments

• OK indique la réponse et contient un résultat valide.
  
• NOT_FOUND indique que l'origine et/ou la destination de ce couplage n'ont pas pu être géocodées.
  
• ZERO_RESULTS indique qu'aucun itinéraire n'a pu être trouvé entre l'origine et la destination.
  
• MAX_ROUTE_LENGTH_EXCEEDED indique que l'itinéraire demandé est trop long et ne peut pas être traité.
  
• UNKNOWN_ERROR indique qu'une demande Distance Matrix n'a pas pu être traitée en raison d'une erreur du serveur. La demande peut aboutir si vous réessayez.
  

Messages d'erreur

Lignes

Éléments

• statut : Voir Codes d'état pour obtenir la liste des codes d'état possibles.
  
• durée : durée nécessaire pour parcourir cet itinéraire, exprimée en secondes (le champ de valeur) et sous forme de texte.
  
• duration_in_traffic : durée nécessaire pour parcourir cet itinéraire, en fonction des conditions de circulation actuelles et historiques.
  
• distance : distance totale de cet itinéraire, exprimée en mètres (valeur) et sous forme de texte. La valeur textuelle utilise le système d'unités spécifié avec le paramètre d'unité de la demande d'origine, ou la région de l'origine.
  
• distance_in_traffic_model : distance la plus courte nécessaire pour parcourir cet itinéraire, en fonction des conditions de circulation actuelles et historiques.