Présentation de l'API Routes programmées
Planifiez et optimisez les itinéraires de vos flottes de véhicules tout en tenant compte des créneaux horaires de service, des limites de capacité, des conditions de circulation et des pauses des conducteurs. Soumettez un problème et obtenez une solution optimisée.
Cette API a été conçue pour optimiser la planification des itinéraires et la gestion des horaires des flottes de véhicules, en tenant compte de contraintes essentielles telles que les créneaux horaires de service, les limites de capacité et les conditions de circulation. En exploitant cette API, les entreprises peuvent améliorer considérablement l'efficacité de leurs livraisons, réduire leurs coûts d'exploitation et gagner un temps précieux grâce à des solutions optimisées de planification des itinéraires et des horaires.
Fondamentalement, l'API résout le problème de l'itinéraire des véhicules (VRP) en tenant compte des enlèvements et des livraisons. Ce problème consiste à calculer les itinéraires les plus efficaces pour une flotte devant se rendre à plusieurs endroits afin d'effectuer des enlèvements et des livraisons, tout en respectant des contraintes telles que les créneaux horaires, la capacité des véhicules et leur disponibilité.
De plus, l'API prend en charge les ajustements dynamiques ou la réoptimisation des plannings. Si vous devez modifier un planning existant, que ce soit en raison de nouvelles commandes, d'annulations ou d'autres changements, vous pouvez fournir une version mise à jour de votre planning en précisant le statut des missions et la position des véhicules. L'API réoptimisera alors le planning pour tenir compte de ces changements, garantissant ainsi une efficacité constante de vos opérations.
Pour savoir comment vous lancer rapidement et commencer à utiliser l'API, consultez la section « Pour commencer ». Plusieurs tutoriels rapides sont également disponibles dans la section « Tutoriels ».
- La version 1.1 prend désormais en charge les modèles de route.
- La version 1.2 permet désormais de configurer de manière flexible la capacité des véhicules.
Guide de démarrage rapide
« Scheduled Routes » est une API asynchrone : envoyez un problème de routage et de planification, recevez un identifiant de référence, puis interrogez cet identifiant jusqu'à ce que la solution optimisée soit prête.
Envoyez vos requêtes en incluant un jeton d'accès API dans l'en-tête « Authorization ».
Utilisation POST /raas/optimization avec un problem charge utile.
Utilisation GET /raas/optimization/{id} jusqu'à ce que la solution soit renvoyée.
Authentification
Les requêtes utilisent un jeton d'accès « bearer » dans le Authorization En-tête. Remplacer YOUR_ACCESS_TOKEN avec le jeton d'accès à l'API que vous avez généré.
Authorization: Bearer YOUR_ACCESS_TOKENLa documentation source d'origine contenait des exemples de jetons au porteur et d'identifiants de test. Ce fichier compatible avec WordPress conserve les exemples et les étapes, mais utilise des espaces réservés tels que YOUR_ACCESS_TOKEN, YOUR_EMAIL, et YOUR_PASSWORD afin que les identifiants ne soient pas publiés par inadvertance.
Cycle de vie de l'API #
L'API propose deux méthodes principales pour gérer l'optimisation du routage et de la planification :
- POST d'optimisation — Envoyez un problème d'optimisation d'itinéraire et de planification. Après avoir envoyé une requête POST, vous recevrez un identifiant de référence unique.
- Optimisation GET — Récupère le statut d'un problème soumis à l'aide de l'identifiant de référence unique obtenu via la méthode POST. Si la solution d'optimisation est prête, vous pouvez obtenir la solution du problème d'optimisation.
Comment fonctionne l'optimisation #
Pour résoudre un problème d'optimisation des itinéraires et des horaires pour une flotte de véhicules, procédez comme suit :
- Définissez le problème. Commencez par décrire votre problème en suivant le format indiqué dans la section « Problème ».
- Envoyez votre requête. Utilisez la méthode POST, comme décrit dans la section « Pour commencer », pour envoyer votre requête à l'API.
- Récupérer la solution. Accédez à la solution de votre problème d'optimisation à l'aide de la méthode GET. Le format de la solution est décrit dans la section Solution.
Pour en savoir plus sur les différents termes utilisés dans l'API, consultez le glossaire. Pour consulter la liste des questions fréquemment posées, consultez la FAQ.
POST /raas/optimisation #
Utilisez cette méthode pour soumettre votre problème d'optimisation d'itinéraires et de planification à l'API. Une fois la requête POST d'optimisation envoyée avec succès, l'API renverra un identifiant de référence unique dans la réponse d'accusé de réception. Utilisez cet identifiant unique pour récupérer la solution à l'aide de la méthode GET d'optimisation (voir la section suivante).
Exemple de requête (cURL)
Exemple d'envoi d'un problème d'optimisation à l'aide de la méthode POST, avec un jeton et une charge utiles types. Dans cet exemple, le problème à traiter se trouve dans un fichier nommé payload.json. Remplacer le jeton d'exemple YOUR_ACCESS_TOKEN avec votre propre jeton. Le schéma du problème d'entrée est défini dans le Problème section.
Schéma de réponse
Une fois la requête POST envoyée, vous recevrez un message de réponse au format suivant :
Si la soumission aboutit, le status sera 202, avec le message indiquant « accepté » et le id qui correspond au numéro de référence unique de l'opération asynchrone. Cet identifiant sert à suivre l'état de l'opération et à récupérer les résultats ultérieurement.
En cas d'erreur, le status affichera un code d'erreur, le id sera nul ou vide, le message sera un « échec », et le error décrira l'erreur. Pour plus de détails, consultez les codes d'état POST ci-dessous.
Exemple de requête (Windows PowerShell)
Le script ci-dessous montre comment effectuer une requête POST à l'aide d'une charge utile d'exemple dans Windows PowerShell. Il part du principe que la charge utile d'entrée est stockée dans un fichier nommé payload.json, et le jeton d'accès à l'API est enregistré dans token.txt. Lors de l'exécution, l'identifiant généré est enregistré dans id.txt. Pour lancer PowerShell, il suffit de taper « PowerShell » dans le menu Démarrer ou dans la ligne de commande.
Codes d'état POST
| Code | Description | Remarques supplémentaires |
|---|---|---|
| 202 | La demande a été acceptée pour traitement. | Un identifiant de référence vous est fourni ; vous pouvez l'utiliser dans une requête GET pour récupérer la solution dès qu'elle est prête. |
| 400 | Échec de la validation des données saisies (erreur de requête). | Paramètre manquant ou non valide, ou type de valeur incorrect. Vérifiez les données saisies et réessayez. |
| 403 | Demande non autorisée. | Cela se produit lorsque l'authentification échoue. |
| 404 | Chemin d'accès demandé introuvable. | Cela se produit lorsqu'un chemin d'accès incorrect est utilisé. |
| 429 | Trop de demandes. | Limite de débit dépassée (nombre de requêtes par minute ou quota atteint). |
| 500 | Erreur interne du service. | Problème de notre côté. Contactez support@ddswireless.com. |
GET /raas/optimization/{id} #
Utilisez cette méthode pour récupérer la solution optimisée correspondant aux tâches d'optimisation créées à l'aide de la méthode POST d'optimisation. Pour ce faire, vous devez indiquer l'identifiant de référence reçu lors de l'appel de la méthode POST.
Exemple de requête (cURL)
Exemple permettant d'obtenir la réponse de l'API à l'aide de la méthode GET avec un identifiant. Remplacer ID dans l'URL avec l'identifiant obtenu via la méthode POST, et n'oubliez pas d'utiliser votre propre jeton d'accès à l'API.
Par exemple, si ID est égal à 5, utilisez ceci :
Schéma de réponse
Si la solution est prête, statistics, routes, et unassigned sera renseigné en fonction de la solution obtenue. Sinon, comme pour la méthode POST, status, message, et error affichera le statut ou l'erreur.
Le schéma de la solution de sortie est défini dans la section Solution.
Exemple de requête (Windows PowerShell)
Le script ci-dessous montre comment effectuer une requête GET en utilisant un identifiant généré par la méthode POST. Il part du principe que cet identifiant est stocké dans un fichier nommé id.txt, et le jeton d'accès à l'API est enregistré dans token.txt. Une fois l'exécution terminée, la réponse générée est enregistrée dans response.txt.
Codes d'état GET
| Code | Description | Remarques supplémentaires |
|---|---|---|
| 200 | La requête a abouti. | La solution est renvoyée via statistics, routes, et unassigned. |
| 202 | La demande a été acceptée, mais n'a pas encore été traitée. | Le statut est « en attente ». Veuillez revenir plus tard pour vérifier si une solution est disponible. |
| 400 | Impossible de traiter la requête (erreur de requête). | Aucune solution viable n'a pu être générée en raison d'une entrée ou de paramètres non valides. |
| 401 | Demande non autorisée. | Une authentification de l'utilisateur est requise. Aucune information d'identification valide n'a été reçue. |
| 500 | Erreur interne du service. | Une erreur s'est produite de notre côté. Contactez-nous support@ddswireless.com. Des champs tels que statistics, routes, et unassigned sera vide. |
Formats de code
Utilisez le même flux d'endpoint dans le format de votre choix. Ces exemples reprennent la structure de requête indiquée dans la documentation de l'API et utilisent des espaces réservés adaptés à la publication.
Soumettre un problème d'optimisation
cURL
curl -X POST "https://iq.scheduledroutes.ddswireless.net/raas/optimization" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d @payload.jsonPython
import json
import requests
url = "https://iq.scheduledroutes.ddswireless.net/raas/optimization"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
}
with open("payload.json", "r", encoding="utf-8") as payload_file:
payload = json.load(payload_file)
response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()
print(response.json())PowerShell
$token = Get-Content token.txt -Raw
$headers = @{
Authorization = "Bearer $token"
"Content-Type" = "application/json"
}
$body = Get-Content payload.json -Raw
$response = Invoke-RestMethod -Uri "https://iq.scheduledroutes.ddswireless.net/raas/optimization" -Method Post -Headers $headers -Body $body
$response.id | Out-File -Encoding utf8 id.txt
Write-Output $responseRécupérer un résultat d'optimisation
cURL
curl -X GET "https://iq.scheduledroutes.ddswireless.net/raas/optimization/ID" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Python
import requests
optimization_id = "ID"
url = f"https://iq.scheduledroutes.ddswireless.net/raas/optimization/{optimization_id}"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
}
response = requests.get(url, headers=headers, timeout=60)
response.raise_for_status()
print(response.json())Objets
L'objet de la requête porte sur problem. L'objet de réponse est centré sur solution. Les références, exemples, schémas, remarques et règles d'origine sont conservés ci-dessous.
Problème, Flotte / Véhicule / Équipe / Pause, Mission / Tâche / Enlèvement / Livraison, Objectif et Configuration.
L'objet « Problème » #
Le Problème Cette entité correspond à un problème de routage et de planification. Comme le montre la figure ci-dessous, elle se compose de quatre éléments principaux : fleet, jobs, objective, et configuration. Parmi ceux-ci, fleet et jobs sont obligatoires, alors que objective et configuration sont facultatifs.
Pour indiquer un lieu ou une adresse dans l'API, utilisez des coordonnées géographiques WGS84 avec au moins 5 décimales pour garantir la précision. Par exemple, l'adresse « 1600 Amphitheatre Parkway, Mountain View, Californie » a pour coordonnée de latitude 37.423021 et la longitude -122.083739. Vous pouvez le spécifier comme suit : "location": {"lat": 37.423021, "lng": -122.083739} ou bien [37.423021, -122.083739].
L'API utilise le format ISO 8601 pour les horodatages, y compris les informations relatives au fuseau horaire, afin de définir l'heure locale de la zone pour laquelle vous souhaitez optimiser l'itinéraire et la planification. Par exemple, 2024-07-31T14:45:30-08:00 correspond au 31 juillet 2024 à 14 h 45 min 30 s PST, soit 8 heures de moins que le temps universel coordonné (UTC).
Dans la charge utile d'entrée, vous devez utiliser systématiquement le même fuseau horaire local. Si plusieurs fuseaux horaires sont détectés, l'API renverra une erreur. Les heures des arrêts programmés dans la réponse de sortie seront fournies dans le même format que celui spécifié dans la charge utile d'entrée. Par exemple, si vous spécifiez 2024-07-31T14:45:30-08:00 Dans vos données d'entrée, les temps de trajet optimisés dans les données de sortie utiliseront également -08:00; si vous utilisez +05:30 en fonction de l'entrée, la sortie utilisera +05:30.
Tous les attributs facultatifs peuvent être omis dans le corps du message. Les tableaux vides (par exemple []) peut également être utilisé pour les attributs facultatifs qui acceptent un tableau.
Veillez à ce qu'aucune information confidentielle ou personnelle ne figure dans les données transmises à l'API. Évitez par exemple d'utiliser des identifiants réels, tels que des numéros d'immatriculation, comme identifiant de véhicule ou comme identifiant de tâche.
Résumé des composants
Spécifie une liste de véhicules ainsi que les informations associées, telles que les horaires de service, les lieux de départ et d'arrivée, les pauses, les capacités et les compétences. Pour chaque véhicule, vous pouvez définir un ou plusieurs horaires de service (heures et lieux de départ/d'arrivée), une ou plusieurs pauses (plage horaire, lieu et durée), un ou plusieurs types de capacité avec les unités disponibles (unités multidimensionnelles telles que le volume, la masse ou la taille), et une ou plusieurs compétences lui permettant d'effectuer certaines tâches. Par exemple, vous pouvez attribuer « poste à souder » et « bouteille d’oxygène » comme compétences à un véhicule, et « élévateur » comme compétence à un autre ; si une tâche nécessite un élévateur, seul le véhicule doté de cette compétence pourra l’effectuer. Vous pouvez également définir des limites telles que le nombre maximal d’arrêts et la distance maximale à parcourir (en kilomètres).
Spécifie une liste des missions que les véhicules doivent effectuer dans le fleet. Chaque mission peut comprendre une série de tâches, qu'il s'agisse uniquement d'enlèvements, uniquement de livraisons, ou à la fois d'enlèvements et de livraisons. Pour les missions de « visite » où vous devez vous rendre sur place pour effectuer un travail (par exemple, des réparations ou l'installation d'un modem), considérez-les comme une tâche de livraison, avec ou sans exigence de capacité. Pour chaque tâche, vous pouvez définir des attributs tels que le lieu, les créneaux horaires, la durée, les exigences de capacité et les compétences requises. Si l'optimiseur ne parvient pas à trouver une heure d'arrivée estimée (ETA) appropriée pour une tâche dans le créneau horaire spécifié, la tâche reste non attribuée. Pour les tâches flexibles ou non urgentes, spécifiez un créneau horaire plus large (durée maximale de 24 heures).
Définit l'objectif ou la stratégie d'optimisation. Actuellement, trois objectifs sont pris en charge :
- Réduire au minimum la durée totale des trajets — stratégie par défaut ; minimise la durée totale des trajets de la flotte tout en effectuant les missions spécifiées.
- Réduire le nombre d'itinéraires — permet de diminuer le nombre de véhicules nécessaires pour effectuer les missions. Cela peut toutefois entraîner une augmentation de la durée totale du trajet ou une charge de travail plus importante pour chaque véhicule.
- Répartir la charge de travail entre les itinéraires — répartit équitablement la charge de travail entre tous les véhicules de la flotte. Cette répartition peut entraîner une augmentation de la durée totale du trajet.
Permet de régler les paramètres de l'API ou de modifier les options par défaut. Vous pouvez par exemple choisir d'inclure dans la réponse de l'API un résumé des statistiques d'optimisation (telles que la durée totale du trajet et la distance parcourue) ou une liste des tâches non attribuées.
Schéma de demande de données #
Le schéma de la requête d'entrée permettant de résoudre un problème d'optimisation d'itinéraire est le suivant. Pour soumettre un problème, cette requête doit être incluse dans la méthode POST, comme décrit dans la section « Pour commencer ».
Dans un problème d'optimisation d'itinéraire, une flotte de véhicules cherche à effectuer efficacement un ensemble de missions. Le schéma ci-dessus vous permet de définir votre flotte et vos missions. Dans la version actuelle de l'API, chaque mission peut être :
- Tâches de collecte uniquement — consistent à récupérer des articles le long du parcours et à les livrer au point d'arrivée de celui-ci.
- Tâches de livraison uniquement — impliquent la livraison d'articles chargés dans le véhicule au début du parcours.
- Les tâches d'enlèvement et de livraison (E/L) : elles regroupent ces deux actions, à savoir aller chercher quelque chose à un endroit et l'apporter à un autre.
Il faut prévoir au moins une mission et un véhicule pour cette tâche. Pour les missions de « déplacement » qui nécessitent de se rendre sur place (par exemple, des réparations ou des installations de modems), considérez-les comme des missions de livraison, avec ou sans exigence de capacité.
De plus :
- Si seulement le
pickupsSi un objet est fourni pour une tâche, celle-ci est considérée comme une tâche à retirer uniquement. - Si seulement le
deliveriesSi un objet est fourni pour une tâche, celle-ci est considérée comme une tâche de simple livraison. - Lorsque les deux
pickupsetdeliveriessi ces services sont proposés, la prestation est classée comme une mission d'enlèvement et de livraison.
L'API ne prend pas en charge les missions comportant plusieurs enlèvements et plusieurs livraisons. En d'autres termes, pour une mission de « type enlèvement et livraison » :
- Le
pickupsLe tableau ne doit contenir que un tâche de ramassage. - Le
deliveriesLe tableau ne doit contenir que un tâche de livraison.
L'API ne prend pas non plus en charge les missions sans enlèvement ni livraison. Règles de classification :
- Si seulement
pickupsune fois défini, le poste est classé comme un fixé au pick-up emploi. - Si seulement
deliveriesune fois défini, le poste est classé comme un basé sur la livraison emploi. - Si l'enlèvement et la livraison sont tous deux définis, le point d'ancrage est celui qui comprend une plage horaire de service.
- Si tant l'enlèvement que la livraison ont des plages horaires, la mission est considérée comme étant centrée sur l'enlèvement.
Pour chaque tâche, divers attributs et contraintes peuvent être définis, tels que les exigences en matière de capacité, les créneaux horaires de service et les compétences requises. Les tâches de visite, pour lesquelles il faut se rendre à des endroits spécifiques afin d'effectuer des tâches (par exemple, des réparations), peuvent être considérées comme une forme spécialisée de tâche de livraison (avec ou sans exigences de capacité). Les tâches sont attribuées à des véhicules dont les capacités ou les compétences correspondent aux exigences de la tâche. Par exemple, si une tâche nécessite une nacelle ou une échelle, seuls les véhicules équipés d'une nacelle ou d'une échelle seront utilisés pour effectuer cette tâche.
problem — référence de champ
problème Obligatoire Spécifie le problème d'optimisation de routage et d'ordonnancement que vous souhaitez résoudre. Il comprend les attributs ci-dessous.
fleet
flotte requise Définit les informations relatives à la flotte. Il s'agit d'un tableau d'objets de flotte. Chaque objet de flotte comprend les attributs suivants :
Un identifiant unique pour le véhicule.
Un tableau d'objets de poste. Chaque objet de poste contient des données relatives aux lieux et heures de début et de fin du poste, ainsi qu'un tableau d'objets de pause contenant chacun les lieux et heures de début et de fin de chaque pause. Il est possible de définir plusieurs objets de poste, mais ceux-ci doivent être disjoints. Éléments de chaque objet de poste :
L'heure et le lieu de prise de service.
time— facultatif. Indique l'heure de début du service. Si elle n'est pas précisée, la valeur par défaut est 00:00:00 (minuit) de la date du jour.location— facultatif. Les coordonnées géographiques (latitude et longitude) du point de départ. À indiquer sous forme de tableau[A,B](A = latitude, B = longitude) ou sous la forme{"lat": A,"lng": B}.
L'heure et le lieu de fin de service.
time— facultatif. Indique l'heure de fin du service. Si elle n'est pas précisée, la valeur par défaut est 23 h 59 min 00 s à la date du jour.location— facultatif. Les coordonnées géographiques du lieu de destination. Indiquez-les sous la forme[A,B]ou{"lat": A,"lng": B}.
serviceWindow— obligatoire si l'on utilise des sauts de ligne. La période pendant laquelle la rupture peut se produire.duration— obligatoire si l'on utilise des sauts de ligne. Un nombre entier indiquant la durée de la pause en secondes.location— facultatif. L'emplacement de la rupture, comme[A,B]ou{"lat": A,"lng": B}. Si le lieu n'est pas précisé, la pause est « libre », ce qui signifie qu'elle peut être prise n'importe où, selon la convenance du conducteur.
Exemple — shifts
Un tableau d'objets de capacité. Chaque objet de capacité est un objet clé-valeur défini avec les clés suivantes :
name— obligatoire. Une chaîne de caractères indiquant le nom du type de capacité (par exemple « fauteuil roulant », « coffre », « siège », « bac »).units— obligatoire. Un nombre entier indiquant le nombre d'unités disponibles pour ce type de capacité.
Par exemple, si un véhicule peut transporter 2 passagers et 20 colis, vous pouvez définir sa capacité comme suit :
Une liste des compétences ou des équipements des véhicules, chacun étant représenté par une chaîne de caractères arbitraire propre à votre application. Cela vous permet de personnaliser les capacités de vos véhicules afin qu'elles correspondent aux exigences des missions qu'ils doivent accomplir. Exemple : "skills": ["lift","fridge","oxygen tank"]
Spécifie les contraintes appliquées au véhicule.
maxDistance— facultatif. Un nombre entier indiquant la distance maximale autorisée pour le véhicule, en miles.maxStops— facultatif. Un nombre entier indiquant le nombre maximal d'arrêts (tâches d'enlèvement ou de livraison) que le véhicule peut effectuer au cours d'une même journée de travail.lifoDepth— facultatif. Un nombre entier définissant la profondeur LIFO (Last In First Out) du véhicule.
Indique la dernière position connue du véhicule à l'heure indiquée. Cette information est essentielle pour réoptimiser un itinéraire en cours afin de tenir compte des nouveaux changements, tels que les pannes de véhicules, les retards, les nouvelles missions ou les missions annulées. Lors de la réoptimisation d'un planning existant, vous devez fournir la position de tous les véhicules concernés.
Identifiant unique utilisé pour définir un modèle d'itinéraire. L'API prend en charge le concept de « modèles d'itinéraire », qui vous permet de définir les spécifications d'un type de véhicule particulier et de demander à l'API de générer un nombre précis de ces véhicules à des fins d'optimisation. Un modèle d'itinéraire contient les mêmes informations qu'un itinéraire ou un véhicule, mais vous pouvez spécifier un paramètre « taille » appelé maxInstances pour cela. Par exemple, supposons que vous disposiez de 100 véhicules. Vous pourriez définir 2 ou 3 modèles d'itinéraire :
- Quart de travail de 6 h à 18 h, capacité : 4 personnes, effectif : 60
- Service de 13 h à 1 h, capacité : 4, taille = 50
- Quart de travail de 6 h à 20 h, capacité : 10 personnes, effectif : 35
Cela signifie que l'API peut créer automatiquement jusqu'à 60 véhicules à l'aide du modèle 1 selon les besoins, 5 à l'aide du modèle 2 et 35 à l'aide du modèle 3.
Si routeTemplateId est fourni, maxInstances indique le nombre de modèles de route à générer à partir du modèle de route spécifié.
- Exactement un de
idourouteTemplateIdIl faut choisir l'un ou l'autre, jamais les deux. idetmaxInstancesne peut pas être utilisés ensemble.- Si les deux
routeTemplateIdetmaxInstancessont fournis, l'API utilise le modèle de route pour générer des itinéraires.
jobs
tâches Au moins une requise Un tableau d'objets de tâche. Chaque objet de tâche possède les attributs suivants :
Un identifiant unique pour la tâche.
Un tableau d'objets « Task », chacun définissant une tâche de ramassage.
Un tableau d'objets « Tâche », chacun définissant une tâche de livraison (ou de dépôt).
- L'API ne prend pas en charge les commandes comportant plusieurs points d'enlèvement et plusieurs livraisons.
- L'API ne prend pas en charge les missions sans enlèvement ni livraison.
- Si seulement
pickupssi ce paramètre est spécifié, la tâche est classée comme emploi lié à la collecte. - Si seulement
deliveriessi ce paramètre est spécifié, la tâche est classée comme poste axé sur la prestation. - Si une mission comprend à la fois un enlèvement et une livraison, le point de référence est déterminé par la tâche qui définit une plage horaire.
- Si les deux tâches ont des plages horaires, le travail est considéré comme un travail ancré sur un ramassage.
L'objet Tâche
Chaque objet « Tâche » comprend les attributs suivants :
Un identifiant unique pour la tâche.
Un objet clé-valeur qui spécifie les coordonnées géographiques (latitude et longitude) du lieu où la tâche doit être effectuée. À indiquer sous forme de tableau [A,B] (A = latitude, B = longitude) ou sous la forme {"lat": A,"lng": B}.
Spécifie la plage horaire de service pour l'exécution de la tâche (obligatoire ou facultative selon le cas d'utilisation ; voir les sections « Enlèvements » et « Livraisons » ci-dessus). La plage horaire de service est un tableau de la forme [A, B] où A et B correspondent aux heures de début et de fin. L'API tentera de fournir une heure d'arrivée prévue (ETA) dans la plage horaire indiquée ; si cela s'avère impossible, la tâche sera répertoriée comme non attribuée. Les heures A et B définissent respectivement l'heure la plus tôt et l'heure la plus tard à laquelle une tâche doit être effectuée par un véhicule. Pour les tâches flexibles ou non urgentes, utilisez une plage horaire aussi large que possible (24 heures maximum) afin de donner à l'API plus de flexibilité dans la planification des autres tâches. La version actuelle de l'API ne prend en charge qu'une seule plage horaire par tâche. Pour les tâches de type « enlèvement uniquement » et « livraison uniquement », la plage horaire est obligatoire.
Indique la durée de la tâche en secondes. Il peut s'agir soit d'un nombre entier, soit d'un objet clé-valeur comportant les clés suivantes :
fixed— la durée fixe (en secondes) de la tâche (par exemple, pour trouver une place de stationnement ou faire descendre l'ascenseur).service— la durée (en secondes) nécessaire à l'exécution de la tâche.
Une série d'exigences de capacité pour la tâche. La structure de chaque objet « exigence » est identique à celle de l'objet « capacité » dans l'entité « flotte ». Chaque élément de capacité se compose d'un name (chaîne) et son units (entier). Les noms indiqués doivent correspondre à ceux définis dans l'objet « capacité » de l'entité « flotte ». Par exemple, si une tâche nécessite une capacité de deux places et 20 colis :
Ensemble des compétences ou des équipements nécessaires à l'exécution de la tâche, chacun étant représenté par une chaîne de caractères arbitraire propre à votre application. Seuls les véhicules dont l'ensemble de compétences correspond à celui de la tâche seront pris en compte pour l'exécution de celle-ci. Ces compétences sont mises en correspondance avec celles définies dans l'entité « flotte ». Exemple : "skills": ["lift", "ladder", "welding machine"]
Une chaîne indiquant l'état de la tâche : pending, in_progress, ou performed. C'est essentiel pour réoptimiser un itinéraire en cours. Pour les nouvelles tâches ou celles qui n'ont pas encore été effectuées, réglez-le sur pending. Si la tâche a déjà été effectuée, définissez-la sur performed. Si le véhicule est déjà arrivé sur place et que la mission est en cours, réglez-le sur in_progress. La valeur par défaut est pending. Exemple : "status": "pending"
Spécifie l'identifiant du véhicule attribué aux tâches déjà planifiées. Ceci est essentiel pour réoptimiser un itinéraire en cours. La valeur par défaut est zéro. Pour les nouvelles tâches, définissez-la sur zéro. Pour les tâches existantes déjà attribuées à un véhicule, définissez cet attribut sur l'identifiant du véhicule attribué. Exemple : "vehicleId": 12
Indique l'heure d'arrivée prévue (ETA) actuelle pour les tâches déjà planifiées. Ce paramètre est essentiel pour réoptimiser un itinéraire en cours. La valeur par défaut est 0. Pour les tâches nouvelles ou en cours d'exécution, définissez-la sur 0 ; pour les tâches existantes en attente, définissez-la sur l'ETA actuelle. Exemple : "eta": "2021-07-04T12:13:00-08:00"
objective
objectif entier Facultatif Spécifie l'objectif d'optimisation (stratégie). La valeur par défaut est 1.
| Valeur | Stratégie |
|---|---|
1 | Réduire au minimum la durée totale du trajet (par défaut) |
2 | Réduire au minimum le nombre d'itinéraires |
3 | Répartir la charge de travail entre les itinéraires |
Exemple : "objective": 1
configuration
Configuration ( facultatif ) Permet de définir des paramètres ou des configurations supplémentaires.
Spécifie le type de polyligne de sortie renvoyé pour chaque itinéraire planifié. L'un des none, plain, encoded. Si none, aucune polyligne n'est incluse. Si plain, une liste ordonnée des intersections à traverser entre chaque paire d'arrêts consécutifs est renvoyée. Si encoded, la polyligne est convertie en une chaîne de caractères que vous pouvez transmettre à des API de navigation tierces, telles que Google Maps, pour obtenir des instructions détaillées. La valeur par défaut est none.
Indicateur permettant de déterminer si les tâches non attribuées doivent être incluses dans la réponse de sortie. La valeur par défaut est False. Si, pour une raison quelconque, l'API ne parvient pas à attribuer une tâche à un itinéraire, elle l'indiquera comme non attribuée.
Indicateur permettant de déterminer si les statistiques d'optimisation doivent être incluses dans la solution finale. La valeur par défaut est True.
Spécifie les unités utilisées pour les statistiques de sortie et les limites de la flotte. Soit metric ou imperial. La valeur par défaut est metric.
Définit la durée maximale de traitement de toutes les tâches. Elle est définie par un tableau statique dont chaque ligne est un tableau contenant trois valeurs temporelles (en minutes) : [A, B, C]. Cela signifie que si la durée de trajet directe pour une mission se situe entre A et B, la durée maximale à bord est égale à « rideTime + C ». Par exemple, voici un tableau simple comportant deux lignes : "maxRideTable":[[0, 10, 30], [11, 20, 40]]. La valeur par défaut est [[0, 300, 720]]. Ce tableau ne doit comporter ni chevauchements ni lacunes, et la granularité est de l'ordre de la minute.
Détermine la manière dont le moteur d'optimisation traite les tâches précédemment attribuées lors d'une réoptimisation. La valeur par défaut est false.
Lorsqu'il est réglé sur true, toutes les tâches déjà attribuées à un véhicule dans la charge utile de réoptimisation sont considérées comme verrouillées et doivent rester sur leur véhicule actuel. Le moteur n'optimisera et n'attribuera que les nouvelles tâches qui ne sont pas encore attribuées à un véhicule.
Lorsqu'il est réglé sur false, le moteur est autorisé à modifier les affectations existantes lors d'une réoptimisation. Les tâches précédemment attribuées peuvent être retirées de leur véhicule d'origine si l'affectation n'est plus valide ou optimale. Par exemple, une tâche initialement prévue pour 8 h peut être retirée lors d'une réoptimisation effectuée à 10 h, car elle ne peut plus être accomplie dans le respect des contraintes imposées.
Les définitions de capacité des véhicules peuvent être nommées puis utilisées dans la section « Flotte ». Cela s'avère particulièrement utile pour les définitions complexes, lorsqu'un véhicule peut présenter de nombreuses configurations. Par exemple, si un véhicule peut accueillir soit (10 passagers « valides » et 0 passager « en fauteuil roulant ») SOIT (8 passagers « valides » et 1 passager « en fauteuil roulant »), vous pouvez définir "vehicleCapacities":{"flexBus": [[{"name": "ambulatory", "units": 10}], [{"name": "ambulatory", "units": 8},{"name":"wheelchair", "units": 1}]]}. Ensuite, dans les propriétés de la flotte, vous pouvez utiliser fleet[<index>].capacities: "flexBus" pour chaque flexBus de la flotte. Les capacités spécifiques aux véhicules peuvent également être enregistrées dans votre profil client personnel, où elles deviennent disponibles sans que vous ayez à les redéfinir dans la section de configuration. Si une capacité spécifique à un véhicule figure à la fois dans votre profil personnel et dans la charge utile, c'est la définition de la charge utile qui prévaut.
La durée de la fenêtre de gel, exprimée en minutes. La fenêtre de gel est un concept qui s'applique uniquement à l'optimisation en temps réel et qui s'avère utile lors de la réoptimisation d'un problème. Par exemple, si vous avez déjà optimisé un problème mais que vous souhaitez y apporter des modifications en cours de journée, vous pouvez renvoyer le problème (avec les paramètres appropriés task.status (pour tenir compte de ce qui a déjà été effectué) et définir une fenêtre de gel de 60 minutes. Cela indique à l'optimiseur que la période s'étendant sur 60 minutes à partir de « maintenant » est hors limites : aucune tâche ne peut être ajoutée ou supprimée d'un itinéraire au sein de cette fenêtre de gel.
Un ensemble de types de capacité soumis à la règle LIFO (Last In, First Out). Exemple : "lifoConstrainedCapacities": ['wheelchair', 'scooter']
Exemple — configuration
version
version Facultatif Spécifie la version de l'API. La valeur par défaut est 1.0.
Pour voir divers exemples d'un Problem et découvrez comment utiliser l'API dans différents cas d'utilisation (par exemple, la réoptimisation), voir Tutoriels.
1. Identifiants uniques. Chaque mission doit disposer d'un identifiant unique. Chaque tâche doit disposer d'un identifiant unique. Chaque véhicule doit disposer d'un identifiant unique. Une mission peut partager son identifiant avec une tâche ou un véhicule — cela est autorisé.
2. Contraintes de temps. Chaque problème peut comporter plusieurs éléments liés au temps, tels que les plages horaires des interventions et les rotations des véhicules. L'API détermine la durée minimale parmi toutes les valeurs. Par exemple, si la durée minimale est 2024-09-18T04:32:00-08:00, la valeur maximale est calculée en déterminant l'heure de minuit du jour où le minimum est atteint, puis en ajoutant 33 heures à cet horodatage. Ainsi, dans cet exemple, la durée maximale autorisée est 2024-09-19T09:00:00-08:00. Si un délai quelconque dans le problème (par exemple, le changement de véhicule ou la fenêtre de tâche) dépasse cette limite, l'API renverra un 400 erreur.
L'objet Solution #
Une fois que vous avez soumis un problème via la méthode POST, vous recevez un identifiant de référence unique. Utilisez cet identifiant de référence avec la méthode GET pour consulter le statut du problème soumis. Si la solution d'optimisation est prête, vous pouvez y accéder dans le solution entité de la réponse. Comme le montre la figure ci-dessous, le solution Cette entité se compose de trois parties principales :
Comprend divers indicateurs qui offrent une vue d'ensemble de la solution dans son intégralité, tous itinéraires confondus, vous permettant ainsi d'évaluer son efficacité (par exemple, la distance totale parcourue pour tous les itinéraires optimisés). L'analyse de ces statistiques vous permet de mesurer la qualité et l'efficacité de la solution générée.
Contient les itinéraires optimisés, ainsi que leurs arrêts et leurs heures d'arrivée prévues (ETA). Il peut également inclure la polyligne de chaque itinéraire.
Contient la liste des tâches non attribuées. Si l'API ne parvient pas à attribuer une tâche à un itinéraire lors de l'optimisation, celle-ci est répertoriée comme non attribuée. Cette liste peut inclure les raisons pour lesquelles chaque tâche reste non attribuée, ce qui permet de mieux comprendre les contraintes ou les problèmes ayant empêché l'attribution.
Schéma de la solution de sortie #
Le modèle de la solution fournie dans la réponse de l'API se présente comme suit :
Le solution Cette entité représente la solution du problème d'optimisation d'itinéraire et comprend les attributs décrits ci-dessous.
statistics
Contient les statistiques de l'ensemble de la solution. Il comprend les propriétés suivantes :
totalDistance— la distance totale parcourue par l'ensemble de la flotte, y compris la distance entre le point de départ et le point d'arrivée de chaque véhicule.revenueDistance— la distance totale parcourue par l'ensemble de la flotte, y compris la distance entre le premier et le dernier arrêt pour chaque véhicule. Elle n'inclut pas la distance entre le point de départ du véhicule et le premier arrêt, ni celle entre le dernier arrêt et le point d'arrivée du véhicule.
used— le nombre de véhicules utilisés dans le cadre de la solution pour effectuer les travaux/tâches programmés.unused— le nombre de véhicules inutilisés.
scheduledTasks— le nombre de tâches planifiées.unassignedTasks— le nombre de tâches non attribuées.
totalHours— le nombre total d'heures de trajet pour l'ensemble de la flotte, y compris le temps passé à se rendre du point de départ de chaque véhicule à sa destination finale.revenueHours— le nombre total d'heures de trajet de l'ensemble de la flotte, y compris le temps écoulé entre le premier et le dernier arrêt pour chaque véhicule. Ce chiffre n'inclut pas le temps de trajet entre le point de départ du véhicule et le premier arrêt, ni entre le dernier arrêt et le point d'arrivée du véhicule.
Exemple — statistics
routes
Fournit un tableau présentant l'itinéraire prévu pour chaque véhicule. Chaque itinéraire prévu comprend :
Le numéro d'identification du véhicule attribué.
Un tableau d'objets de service. L'API prend en charge plusieurs services pour chaque véhicule. Chaque objet de service comprend :
index— l'indice du décalage (entier).stops— une liste de tous les arrêts que le véhicule doit effectuer au cours de ce service.
Chaque étape présente les caractéristiques suivantes :
ordinal— la position de l'arrêt dans l'horaire, représentée par son index (nombre entier).jobId— l'identifiant de la tâche associé à cet arrêt (entier).taskId— l'identifiant de la tâche associé à cet arrêt (entier).type— le type de prestation effectuée à cet arrêt (« enlèvement » ou « livraison »).location— les coordonnées géographiques de l'emplacement de l'arrêt.eta— l'heure d'arrivée prévue à l'arrêt (dans le même fuseau horaire que la charge utile saisie).timeToNext— le temps de trajet jusqu'à l'arrêt suivant. Par exemple, si vous déposez un passager à 9 h et que votre prochaine course est à 10 h, cela signifie que le temps de trajet entre l'arrêt actuel et le prochain arrêt est de 20 minutes.distanceToNext— la distance à parcourir en voiture jusqu'à l'arrêt suivant. Selon les unités sélectionnées dans la configuration, cette distance peut être exprimée en miles ou en mètres.waitTime— combien de temps le conducteur devra attendre au prochain arrêt s'il démarre maintenant.polyline— la polyligne reliant l'arrêt à l'arrêt précédent. Si « plain » est spécifié dans la configuration, la polyligne est une liste ordonnée des intersections à parcourir entre l'arrêt précédent et l'arrêt actuel. Si « encoded » est spécifié, la polyligne « plain » est encodée et renvoyée sous forme de chaîne encodée.break— si l'arrêt prévu correspond à une pause, cet élément indique l'identifiant de la pause. Les autres arrêts ne comportent pas cet élément. L'API n'impose pas que les pauses (ou les tâches) soient répertoriées par ordre chronologique.
Exemple — routes
unassigned
La liste facultative des tâches non attribuées contient les tâches qui ne peuvent pas être attribuées en raison de contraintes spécifiques. Chaque élément comprend un identifiant de travail, un identifiant de tâche et, le cas échéant, les motifs de non-attribution (un code accompagné d'une description) :
job— l'identifiant de la tâche (entier) qui n'a pas encore été attribuée.task— l'identifiant (entier) de la tâche non attribuée.
Une série de raisons possibles pour lesquelles certaines tâches n'ont pas été attribuées.
code— le code (entier) correspondant à la cause possible.description— la description (chaîne de caractères) de la raison possible.
Erreurs et codes d'état #
Comme indiqué dans la section « Pour commencer », l'API prend en charge les méthodes POST et GET. Selon la méthode utilisée, elle renvoie un code d'état dans la réponse. Vous trouverez ci-dessous la description des codes d'état pour ces deux méthodes.
Codes d'état POST
| Code | Description | Remarques supplémentaires |
|---|---|---|
| 202 | La demande a été acceptée pour traitement. | Un identifiant de référence est renvoyé ; il peut être utilisé dans une requête GET pour récupérer la solution dès qu'elle est prête. |
| 400 | Échec de la validation des données saisies (erreur de requête). | Un ou plusieurs paramètres manquent, sont incorrects ou ont été saisis de manière erronée. Veuillez corriger les données saisies et renvoyer la demande. |
| 403 | Identifiants d'authentification non valides ou autorisations insuffisantes. | La requête a été reçue, mais l'utilisateur n'est pas autorisé en raison d'autorisations manquantes ou incorrectes. |
| 404 | Chemin d'accès demandé introuvable. | Cette erreur se produit lorsque le chemin d'accès URL demandé ne correspond à aucun point de terminaison valide. |
| 429 | Trop de demandes. | Le quota de requêtes par minute (QPM) a été dépassé. Le client doit réduire la fréquence de ses requêtes. |
| 500 | Erreur interne du service. | Un problème côté serveur est survenu au niveau de l'API. Veuillez contacter support@ddswireless.com pour obtenir de l'aide. |
Codes d'état GET
| Code | Description | Remarques supplémentaires |
|---|---|---|
| 200 | La requête a abouti. | Le problème a été résolu avec succès. Les résultats sont renvoyés via statistics, routes, et unassigned. |
| 202 | La demande a été acceptée, mais elle n'est pas encore traitée (statut « en attente »). | La solution n'est pas encore disponible. Veuillez revenir plus tard. |
| 400 | Impossible de traiter la requête (erreur de requête). | Il n'a pas été possible de générer une solution viable pour les emplacements ou les paramètres fournis. |
| 401 | Demande non autorisée. | La requête nécessite une authentification de l'utilisateur. Le serveur n'a pas reçu les informations d'identification requises. |
| 500 | Erreur interne du service. | Nous avons rencontré un problème côté serveur avec notre API. Veuillez contacter support@ddswireless.com. Les champs statistics, routes, et unassigned sera vide. |
Guides / Tutoriels #
Vous trouverez ici divers exemples illustrant l'utilisation de l'API. L'API prend principalement en charge deux cas d'utilisation principaux :
- Planification et ordonnancement — génère un planning optimisé pour les tournées d'une flotte, en tenant compte des contraintes liées aux missions et aux véhicules.
- Réoptimisation — consiste à modifier un planning existant ou en cours afin de tenir compte de changements tels que de nouvelles missions, des annulations ou des pannes de véhicules.
Consultez les exemples ci-dessous pour découvrir comment ces cas d'utilisation sont mis en œuvre :
- Exemple 1 — Planification d'un scénario simple d'enlèvement et de livraison (dépôt).
- Exemple 2 — Un scénario simple de réoptimisation visant à ajouter de nouvelles tâches à un planning existant.
- Exemple 3 — Réoptimisation avec des tâches annulées.
- Exemple 4 — Réoptimisation avec des véhicules en panne.
Les lieux mentionnés dans les exemples suivants sont fictifs et générés aléatoirement ; ils ne correspondent à aucun lieu réel.
Planification d'un scénario simple d'enlèvement et de livraison
Une flotte de deux véhicules assurant trois missions d'enlèvement et de livraison, optimisée pour réduire au minimum la durée totale des trajets.
Dans cet exemple, notre flotte se compose de deux véhicules et nous avons trois missions d'enlèvement et de livraison qui doivent être effectuées par ces deux véhicules. Voici les détails pour chaque véhicule :
Véhicule 1
- Détails du service : Le service commence le 1er octobre 2024 à 8 h 00 (heure du Pacifique) au point de repère (50.67293, -120.34195) et se termine à 18 h 00 au même endroit. Le fuseau horaire étant le PST, l'heure de début est enregistrée comme
2024-10-01T08:00:00-08:00et l'heure de fin comme2024-10-01T18:00:00-08:00. - Pauses : deux pauses de 15 minutes chacune. Première pause entre 10 h 00 et 10 h 30 au point (50.6531, -120.38393) ; deuxième pause entre 14 h 00 et 14 h 30 au point (50.6531, -120.38393).
- Capacité : 15 places et 5 places pour le fret.
- Caractéristiques : Équipé d'un ascenseur et de la climatisation.
Véhicule 2
- Détails du service : Le service commence le 01/10/2024 à 8 h 00 (heure du Pacifique) au point de repère (50,7117, -120,39286) et se termine à 18 h 00 au point de repère (50,67698, -120,32012).
- Pauses : une pause de 15 minutes entre 11 h et 11 h 30 au point de repère (50.6531, -120.38393).
- Capacité : 10 places et 8 bagages.
- Capacités : Équipé uniquement d'un ascenseur.
Nous proposons également trois missions de « collecte et livraison » à Kamloops, en Colombie-Britannique (Canada). Voici les détails de chaque mission :
Offre d'emploi n° 1
- Prise en charge : Lieu (50.65391, -120.37365). Plage horaire : de 9 h à 9 h 30 (la mission est liée à la prise en charge, qui doit avoir lieu pendant cette plage horaire). Durée : 10 minutes. Exigences : 1 place assise, 2 colis, véhicule équipé d'un hayon élévateur.
- Livraison : Adresse (50.69409, -120.35425). Durée : 5 minutes.
Emploi 2
- Prise en charge : Coordonnées (50.70816, -120.37796). Durée : 5 minutes. Conditions requises : 1 place, véhicule équipé d'un hayon élévateur et de la climatisation.
- Livraison : Coordonnées (50.66559, -120.36924). Plage horaire : de 12 h 45 à 13 h 30 (la mission est liée à la livraison, qui doit être effectuée pendant cette plage horaire). Durée : 5 minutes.
Job 3
- Prise en charge : Lieu (50.70393, -120.37263). Plage horaire : de 14 h à 14 h 30 (la mission est liée au lieu de prise en charge). Durée : 10 minutes. Exigences : 1 place assise, 3 colis, aucun équipement spécifique requis.
- Livraison : Adresse (50.69028, -120.39028). Durée : 5 minutes.
Notre objectif est d'attribuer ces missions aux véhicules définis de manière à minimiser la durée totale du trajet. En d'autres termes, notre objectif d'optimisation est égal à 1. Le problème à résoudre est le suivant :
Problème d'entrée (charge utile)
Après avoir envoyé ce problème via la méthode POST (comme décrit dans la section « Pour commencer »), nous obtenons la solution suivante via la méthode GET :
Solution de sortie
Ajouter de nouvelles tâches à un planning existant
Réoptimiser un planning partiellement exécuté à 11 h 36 min 34 s afin d'y intégrer une nouvelle tâche reçue.
Reprenons maintenant l'exemple précédent. Supposons que vous ayez commencé à exécuter le planning établi dès ce matin, qu'il soit actuellement 11 h 36 min 34 s et que vous receviez un nouvel ordre de travail comme suit :
Emploi n° 4 (un nouvel emploi)
- Prise en charge : Coordonnées (50.65187, -120.40052). Plage horaire : de 15 h 45 à 16 h 15 (mission avec point de prise en charge fixe). Durée : 15 minutes. Exigences : 1 place assise, 1 colis.
- Livraison : Adresse (50.69262, -120.35412). Durée : 10 minutes.
Vous avez déjà terminé la tâche 1, mais les tâches 2 et 3 sont toujours en cours, avec les détails suivants :
- Tâche n° 1 : effectuée.
- Tâche n° 2 : en cours. Enlèvement — véhicule n° 1, heure d'arrivée prévue à 10 h 30. Livraison — véhicule n° 1, heure d'arrivée prévue à 12 h 45.
- Tâche n° 3 : en cours. Enlèvement — véhicule n° 2, heure d'arrivée prévue à 14 h. Livraison — véhicule n° 2, heure d'arrivée prévue à 14 h 29.
Les tâches 2 et 3 étant en cours d'exécution, elles sont associées à un identifiant de véhicule et à une heure d'arrivée prévue. Pour réoptimiser votre planning afin d'y inclure la nouvelle tâche (tâche 4), fournissez une vue actualisée de votre planning actuel via l'API. Cela comprend les informations suivantes concernant vos tâches :
- Poste n° 1 : déjà effectuées, veuillez donc définir le statut des tâches de collecte et de livraison sur
"status":"performed". Vous n'avez pas besoin d'indiquer l'identifiant actuel du véhicule ni l'heure d'arrivée prévue pour ces tâches, car celles-ci ont déjà été effectuées et ne peuvent plus être modifiées. - Job 2 : toujours en cours et attribué au véhicule 1, avec une heure d'arrivée prévue pour l'enlèvement à 10 h 30 et une heure d'arrivée prévue pour la livraison à 12 h 45. Inclure
"status": "in_progress","vehicleId": 1, ainsi que leetapour ses opérations d'enlèvement et de livraison. - Job 3 : toujours en cours et attribué au véhicule 2, avec une heure d'arrivée prévue pour l'enlèvement à 14 h et une heure d'arrivée prévue pour la livraison à 14 h 29. Inclure
"status": "in_progress","vehicleId": 2, ainsi que leetapour ses opérations d'enlèvement et de livraison. - Job 4 : une nouvelle tâche, dont la date n'est pas encore fixée, donc définissez son statut sur
"status":"pending". Vous n'avez pas besoin d'indiquer un identifiant de véhicule ni une heure d'arrivée prévue. Une fois la réoptimisation effectuée, vous obtiendrez un identifiant de véhicule et une heure d'arrivée prévue pour chaque tâche de cette mission.
Vous devez également indiquer la dernière position connue de vos véhicules afin que l'API dispose d'une image actualisée de votre planning actuel. Supposons que les dernières positions connues à 11 h 36 min 34 s (l'heure à laquelle nous souhaitons réoptimiser) soient les suivantes : Véhicule 1 : (50,66692, -120,35293) et Véhicule 2 : (50,65324, -120,37398). Inclure un lastKnownLocation objet contenant l'emplacement et time pour chaque véhicule.
Pour procéder à une nouvelle optimisation, vous pouvez désormais soumettre votre nouveau problème d'optimisation comme suit :
Réoptimisation de la charge utile
Réoptimisation avec les tâches annulées
Supprimer les tâches annulées d'un planning existant et réoptimiser celles qui restent.
Si vous avez soumis un problème d'optimisation pour un ensemble de tâches et que vous disposez déjà d'un planning, mais que certaines tâches ont été annulées, vous pouvez réoptimiser votre planning en retirant les tâches annulées du problème. Pour ce faire, vous devez :
- Donnez un aperçu actualisé de vos missions en cours et des dernières positions connues de vos véhicules, comme dans l'exemple 2.
- Créez et soumettez une version révisée du problème tenant compte de ces modifications.
Une fois la demande envoyée, vous recevrez un nouveau planning tenant compte des missions mises à jour et de l'état de la flotte.
Réoptimisation avec des véhicules hors service
Réattribuer les tâches d'un véhicule tombé en panne en cours de service.
Imaginons qu'il soit 8 h et que vous utilisiez l'API pour générer un planning optimisé pour vos missions avec 10 véhicules. Vous commencez à exécuter le planning, mais à 9 h 14, vous apprenez qu'un de vos véhicules est en panne et ne peut plus effectuer les missions qui lui ont été attribuées. Pour réoptimiser le planning, procédez comme suit :
- Mettez à jour les informations relatives à la flotte. Supprimez le véhicule hors service de votre objet « flotte ».
- Indiquez la position des véhicules. Indiquez les dernières positions connues des véhicules restants, comme dans l'exemple 2.
- Mettre à jour le statut des tâches. Indiquez le statut de toutes les tâches : précisez celles qui ont déjà été effectuées, celles qui sont en cours, ainsi que celles qui sont nouvelles ou en attente. Pour les tâches en cours, indiquez l'identifiant du véhicule concerné et l'heure d'arrivée prévue.
- S'occuper des formalités liées au véhicule accidenté. Modifier le statut de toutes les tâches précédemment attribuées au véhicule en panne pour
"pending". Cela permet à l'API de les réaffecter à d'autres véhicules disponibles et de recalculer leurs heures d'arrivée prévues. - Soumettre pour une nouvelle optimisation. Soumettre le problème mis à jour à l'API afin qu'elle procède à une nouvelle optimisation du planning.
Comment tester les itinéraires planifiés #
Étape 1 — Générer un jeton d'accès
Commencez par envoyer une requête POST à l'URL suivante pour obtenir un jeton d'accès, en utilisant les identifiants ci-dessous.
Corps de la requête POST pour Vancouver (locataire 2) :
Corps de la requête POST pour la Finlande (locataire 3) :
Copiez ensuite le jeton généré. Voici une capture d'écran illustrant cette étape :
Étape 2 — Envoyer une charge utile (problème d'optimisation) à l'API
Pour envoyer une charge utile à l'API et obtenir un identifiant de référence, insérez le jeton généré dans la partie « Authorization » de la requête POST suivante, et insérez la charge utile dans la partie « Body » de la requête.
Exemple de charge utile d'entrée :
Si la méthode POST aboutit, vous obtenez un identifiant de référence qui vous permet de récupérer la réponse via la méthode GET. Voici une capture d'écran illustrant cette étape :
Étape 3 — Récupérer la réponse générée par l'appel à l'API
Pour obtenir la réponse à l'aide de l'ID de référence reçu, insérez le jeton d'accès dans la partie « Authorization » de la requête GET suivante et incluez l'ID de référence dans l'URL.
Voici une capture d'écran de cette étape :
Glossaire n°
| Terme | Définition |
|---|---|
problem | Un problème d'optimisation des itinéraires et des horaires à résoudre par l'API. |
solution | La solution au problème d'optimisation des itinéraires et des horaires fournie par l'API. |
fleet | Un parc automobile désigne une liste de types de véhicules et les informations les concernant. |
job | Une liste des missions de livraison ou de collecte et de livraison qui doivent être effectuées par un véhicule spécifique. |
task | Une tâche fait partie d'un travail et doit être effectuée à un endroit et à un moment précis. |
break | Un attribut permettant de définir une ou plusieurs pauses pour les conducteurs à des emplacements spécifiques. |
demand | Exigence en matière de capacité de charge exprimée en unités multidimensionnelles (par exemple, volume, masse). |
duration | Le temps consacré à l'exécution d'une tâche ou à une pause. |
shifts | Définit les horaires des véhicules, y compris les heures de départ et d'arrivée, les lieux et les pauses éventuelles. |
delivery | Une tâche consistant à livrer un article chargé plus tôt au cours de la tournée. |
pickup and delivery | Une mission pour laquelle les lieux de prise en charge et de livraison sont précisés. |
skills | Compétences requises en matière de véhicules pour accomplir certaines tâches (par exemple, équipement, exigences en matière de dimensions). |
service window | Une période pendant laquelle une tâche doit être accomplie. |
start/end location | Lieu d'où part ou où revient un véhicule (par exemple, dépôt ou garage). |
start/end time | Définit les horaires des quarts de travail, des pauses, des départs ou des tâches. |
location | La latitude et la longitude d'une adresse au format WGS84. |
re-optimization | Mise à jour d'un planning en cours en raison de modifications telles que des commandes nouvelles ou annulées. |
ID (or id) | Un identifiant unique pour un chantier, une tâche ou un véhicule. |
VRP | Problème de routage de véhicules. |
CVRP | Problème de routage de véhicules avec contraintes de capacité. |
PDP | Problème de collecte et de livraison. |
limits | Contraintes appliquées à un type de véhicule. |
objective | La stratégie d'optimisation utilisée pour résoudre le problème. |
statistics | Statistiques relatives aux itinéraires optimisés fournis par la solution. |
stop | Une liste des activités réalisées à un moment et à un endroit précis le long d'un itinéraire. |
unassigned jobs/tasks | Tâches qui n'ont pas pu être affectées à un itinéraire. |
ETA | Heure d'arrivée prévue. Indiquée pour tous les arrêts dans le fichier de sortie. |
polyline | Un tracé formé de points reliés représentant un itinéraire sur la carte. |
encoded polyline | Une version sous forme de chaîne compressée d'une polyligne, utilisée pour réduire au minimum la taille des données (par exemple, _kv~uF|y~wGdkZ~gAx|]t@). |
FAQ n°
| Question | Réponse |
|---|---|
| L'API prend-elle en charge la résolution du problème de collecte et de livraison (PDP) ? | Oui, consultez la section « Tutoriels » pour obtenir des explications détaillées. |
| L'API prend-elle en charge le protocole PDP ouvert ? | Oui, vous pouvez définir librement les points de départ et d'arrivée pour chaque véhicule de votre flotte. |
| L'API utilise-t-elle des données de trafic en temps réel ? | Oui, il utilise à la fois des données de trafic historiques et en temps réel. |
| Puis-je définir les horaires des trajets, les lieux de départ et d'arrivée, ainsi que les pauses ? | Oui, consultez l'objet « flotte » sur la page « Problème ». |
| Peut-on définir plusieurs types de capacité arbitraires pour les véhicules ? | Oui, le capacity L'attribut de l'objet « flotte » prend en charge plusieurs dimensions, telles que le poids, le volume et la quantité. |
| Peut-on définir le nombre maximal de tâches par véhicule ? | Oui, cela peut être défini à l'aide de l'objet « flotte » de la page « Problème ». |
| L'API prend-elle en charge plusieurs pauses par véhicule ? | Oui, cette fonctionnalité est prise en charge via l'objet « Flotte » dans la page « Problèmes ». |
| L'API prend-elle en charge les enlèvements, les livraisons ou les deux ? | Oui, consultez l'objet « jobs » dans la documentation relative au problème. |
| Puis-je définir la durée d'une tâche ? | Oui, utilisez l'attribut « duration » dans l'objet « jobs » du problème. |
| Puis-je définir des exigences arbitraires en matière de capacité des tâches ? | Oui, cela est pris en charge via l'objet « jobs » dans la définition du problème. |
| Peut-on définir une plage horaire de service pour chaque tâche ? | Oui, indiquez les heures de début minimale et maximale à l'aide des plages horaires dans l'objet « jobs ». |
| Puis-je définir les compétences ou les qualités requises pour chaque tâche ? | Oui, les critères sont pris en charge dans l'objet « jobs » et permettent d'associer les tâches aux véhicules ou aux conducteurs qui répondent aux critères. |
| L'API prend-elle en charge la réoptimisation des itinéraires en cours ? | Oui, consultez la rubrique « Tutoriels » pour savoir comment réoptimiser les solutions en cours. |
| L'API fournit-elle des statistiques sur les itinéraires et les horaires ? | Oui, consultez la section « Solution » pour obtenir des statistiques détaillées telles que la durée du trajet, la distance parcourue et les missions non attribuées. |
| L'API explique-t-elle pourquoi certaines tâches n'ont pas été attribuées ? | Oui, consultez la section « Solution » pour connaître les raisons pour lesquelles certaines tâches ne sont pas attribuées. |
| L'API renvoie-t-elle les heures d'arrivée estimées ? | Oui, voir la solution pour connaître les délais estimés par tâche. |
| L'API peut-elle regrouper les tâches par emplacement ? | Oui, le regroupement est pris en charge afin d'améliorer l'efficacité des itinéraires. |
| Puis-je choisir différents objectifs d'optimisation ? | Oui. Les options disponibles sont les suivantes : « Réduire au minimum la durée totale du trajet », « Réduire au minimum le nombre d'itinéraires » et « Répartir la charge de travail entre les itinéraires ». Consultez la section « Problème » pour plus de détails. |