Structure de base (ShipmentModel, Shipment et Vehicle)

ShipmentModel comporte un objet "shipments" avec un type de message "Shipment" et un objet "vehicles" avec un type de message "Vehicle".

L'objectif de l'API Route Optimization est de planifier des itinéraires pour une flotte de véhicules afin de desservir un ensemble de lieux. L'objet OptimizeToursRequest décrit les propriétés de ces véhicules et de ces lieux, et constitue la structure principale du corps de la requête de chaque point de terminaison.

La structure de base de l'objet OptimizeToursRequest est la suivante :

Ce document décrit les types de messages suivants :

  • ShipmentModel: contient la liste des expéditions, des véhicules disponibles et d'autres objets qui décrivent leurs relations.
  • Shipment: décrit les lieux à desservir par un véhicule. Ils peuvent représenter des colis à récupérer et à livrer, ou des lieux où le conducteur du véhicule effectue un service.
  • Vehicle: décrit le moyen de transport entre les lieux d'expédition. Chaque véhicule correspond à un véhicule réel ou à une personne se déplaçant à pied.

ShipmentModel

ShipmentModel contient les éléments du problème d'optimisation de l'itinéraire. Il contient un ensemble d'expéditions qui peuvent être effectuées par un ensemble de véhicules, tout en tenant compte des contraintes et en minimisant le coût global.

Le tableau ci-dessous décrit certaines propriétés pertinentes de ShipmentModel :

Propriétés Description
shipments et vehicles Objets obligatoires contenant les détails d'une ou de plusieurs expéditions et véhicules.
globalStartTime et globalEndTime Indique le début et la fin de la période pendant laquelle tous les véhicules doivent effectuer toutes les expéditions. Bien que ces propriétés ne soient pas obligatoires, il est recommandé de les inclure , car l'optimiseur fonctionne mieux lorsqu'il respecte les contraintes de temps.

Pour obtenir la liste complète des propriétés de ShipmentModel, consultez la documentation de référence.

Exemple ShipmentModel

Dans cet exemple, vous disposez d'un service de garderie pour chiens et vous commencez à créer votre requête. Vous définissez les expéditions et les véhicules ultérieurement, mais vous souhaitez commencer par définir vos horaires d'ouverture et votre coût opérationnel horaire.

Dans cet exemple, les ShipmentModel valeurs de propriété de votre requête sont les suivantes :

Propriété Valeur Description
globalStartTime 2024-02-13T00:00:00.000Z Date et heure de début des horaires d'ouverture.
globalEndTime 2024-02-14T06:00:00.000Z Date et heure de fin des horaires d'ouverture.

Voici un exemple de code d'un ShipmentModel message intégrant les valeurs de scénario de l'exemple.

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

Le type de message Shipment définit la structure de propriété d'une expédition qui peut être livrée ou d'un service pouvant être effectué sur un itinéraire.

Un colis réel correspond à un message "Shipment" (Colis), qui est contenu dans un objet "shipments" (colis).

Comme illustré dans le schéma :

  • Un Shipment message contient toutes les informations d'une expédition ou d'un service réel.
  • Tous les Shipment messages sont spécifiés dans le champ shipments.
  • Le shipments champ contient un ou plusieurs messages Shipment.

Un Shipment message nécessite au moins un pickups ou deliveries objet. La définition de ces objets est la suivante :

  • pickups définit le lieu de collecte d'une expédition.
  • deliveries définit le lieu de livraison d'une expédition.
  • Both pickups et deliveries contiennent un type de message VisitRequest qui définit les lieux et d'autres détails.

Le tableau suivant décrit les différents scénarios en fonction de la configuration de pickups et deliveries dans un message Shipment.

Scénario Description
pickups uniquement Vous êtes censé collecter uniquement l'expédition.
deliveries uniquement Vous êtes censé avoir préchargé l'expédition ou livrer un service.
pickups et deliveries Le véhicule attribué doit d'abord effectuer la collecte, puis la livraison. Seul le véhicule qui a effectué la collecte peut effectuer la livraison.
Plusieurs pickups ou deliveries Si une expédition répertorie plusieurs possibilités pour pickups ou deliveries, l'optimiseur choisit une option de collecte et une option de livraison à utiliser, en fonction de la minimisation des coûts et du respect des contraintes.

Pour obtenir la liste complète des propriétés de Shipment, consultez la documentation de référence.

Exemple Shipment

Dans cet exemple, vous disposez d'un service de garderie pour chiens où vous récupérez les chiens à leur domicile et les livrez à votre garderie. Vous souhaitez définir le lieu de collecte de deux chiens et définir votre établissement comme lieu de livraison :

  • Le domicile du premier chien se trouve à la Coit Tower, à San Francisco. Les coordonnées de ce lieu sont les suivantes : latitude 37.8024 et longitude -122.4058.
  • Le domicile du deuxième chien se trouve au South Sunset Playground Park, à San Francisco. Les coordonnées de ce lieu sont les suivantes : latitude 37.7359 et longitude -122.5011.
  • Votre garderie pour chiens se trouve au Mission Dolores Park, à San Francisco. Les coordonnées de ce lieu sont les suivantes : latitude 37.759773 et longitude -122.427063.

Voici un exemple de code d'un Shipment message, où l'shipments objet contient deux Shipmenttypes de messages avec les coordonnées de l'exemple.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
    ...
    ]
  }
}

Vehicle

Le type de message Vehicle définit la structure de propriété d'un véhicule pouvant effectuer une expédition sur un itinéraire.

Un véhicule réel correspond à un message "Vehicle", qui est contenu dans un objet "vehicles".

Comme illustré dans le schéma :

  • Un Vehicle message contient toutes les informations d'un véhicule réel.
  • Tous les Vehicle messages sont spécifiés dans le champ vehicles.
  • Le vehicles champ contient plusieurs Vehicle messages.

Le tableau suivant décrit certaines propriétés pertinentes d'un Vehicle.

Propriétés Description
startLocation et endLocation Le lieu de départ et d'arrivée des véhicules, qui font partie de l'itinéraire optimisé final. S'ils ne sont pas définis, ils sont définis par défaut sur les lieux de collecte de la première expédition et de livraison de la dernière expédition.
costPerHour, costPerKilometer, costPerTraveledHour Paramètres de coût spécifiques au véhicule. Il est recommandé d'inclure au moins un paramètre de coût dans votre requête pour que l'API renvoie un itinéraire optimisé. Pour en savoir plus sur les coûts, consultez le concept clé Modèle de coût.
startTimeWindows et endTimeWindows Définissent les périodes pendant lesquelles un véhicule peut circuler sur un itinéraire. Ces périodes doivent se situer dans la période globalStartTime et globalEndTime définie dans ShipmentModel. Bien que cette propriété ne soit pas obligatoire, il est recommandé de l'inclure , car l'optimiseur fonctionne mieux lorsqu'il respecte les contraintes de temps.

Exemple Vehicle

Dans cet exemple, vous disposez d'un service de garderie pour chiens et vous souhaitez définir le lieu de votre véhicule au début et à la fin de la journée, ainsi que la quantité d'essence qu'il consomme. Vous n'avez pas besoin de spécifier les heures de travail du véhicule, car elles correspondent aux heures que vous avez définies dans les propriétés globalStartTime et globalEndTime de l'objet ShipmentModel.

Dans cet exemple, les Vehicle valeurs de propriété de votre requête sont les suivantes :

Propriété Valeur Description
startLocation latitude: 37.759773, longitude: -122.427063 Coordonnées de départ de l'itinéraire de votre véhicule. Elles correspondent à l'emplacement de votre garderie pour chiens, située au Mission Dolores Park, à San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Coordonnées de fin de l'itinéraire de votre véhicule. Elles correspondent à l'emplacement de votre garderie pour chiens, située au Mission Dolores Park, à San Francisco.
costPerHour 27 Montant que vous payez à un conducteur pour conduire votre véhicule de garderie pour chiens. Vous payez le conducteur 27 dollars par heure.

Voici un exemple de code d'un Vehicle message intégrant les valeurs de scénario de l'exemple.

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

Pour obtenir la liste complète des propriétés de Vehicle, consultez la documentation de référence.

Exemple de requête complète

L'exemple de code suivant fournit un exemple de requête complet, combinant les ShipmentModel, Shipment et Vehicle exemples présentés dans ce document.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ],
    "globalStartTime": "2024-02-13T00:00:00.000Z",
    "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}