Struttura di base (ShipmentModel, Shipment e Vehicle)

L'obiettivo dell'API Route Optimization è pianificare i percorsi per una flotta di veicoli che devono visitare un insieme di località. L'oggetto OptimizeToursRequest descrive le proprietà di questi veicoli e località ed è la struttura principale del corpo della richiesta di ogni endpoint.

La struttura di base dell'oggetto OptimizeToursRequest è la seguente:

• Il campo model contiene un messaggio ShipmentModel che contiene due campi chiave fields:
  • Un campo shipments, che contiene uno o più messaggi Shipment.
  • Un campo vehicles, che contiene uno o più messaggi Vehicle.

Questo documento descrive i seguenti tipi di messaggi:

• ShipmentModel: contiene l'elenco delle spedizioni, dei veicoli disponibili e di altri oggetti che ne descrivono le relazioni.
• Shipment: descrive le località che un veicolo deve visitare. Possono rappresentare pacchi effettivi da ritirare e consegnare o luoghi in cui l'autista del veicolo esegue un servizio.
• Vehicle: descrive il mezzo di trasporto tra le località di spedizione. Ogni veicolo corrisponde a un veicolo reale o a una persona che si sposta a piedi.

ShipmentModel

ShipmentModel contiene gli elementi del problema di ottimizzazione del percorso. Contiene un insieme di spedizioni che possono essere eseguite da un insieme di veicoli, tenendo conto dei vincoli e riducendo al minimo il costo complessivo.

La tabella seguente descrive alcune proprietà pertinenti di ShipmentModel:

Per l'elenco completo delle proprietà in ShipmentModel, consulta la documentazione di riferimento.

Esempio di ShipmentModel

In questo esempio, hai un servizio di asilo per cani e stai iniziando a creare la richiesta. Definisci le spedizioni e i veicoli in un secondo momento, ma vuoi iniziare impostando l'orario di apertura e il costo operativo orario.

Per questo esempio, i valori delle proprietà ShipmentModel nella richiesta sono i seguenti:

Di seguito è riportato un esempio di codice di un ShipmentModel messaggio che incorpora i valori dello scenario di esempio.

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

Shipment

Il tipo di messaggio Shipment definisce la struttura delle proprietà di una spedizione che può essere consegnata o di un servizio che può essere eseguito su un percorso.

Come illustrato nel diagramma:

• Un messaggio Shipment contiene tutte le informazioni di una spedizione o di un servizio reale.
• Tutti i Shipment messaggi sono specificati nel campo shipments.
• Il campo shipments contiene uno o più messaggi Shipment.

Un messaggio Shipment richiede almeno un oggetto pickups o deliveries. La definizione di questi oggetti è la seguente:

• pickups definisce la località di ritiro di una spedizione.
• deliveries definisce la località di consegna di una spedizione.
• Sia pickups sia deliveries contengono un tipo di messaggio VisitRequest che definisce le località e altri dettagli.

La tabella seguente descrive i diversi scenari in base alla configurazione di pickups e deliveries in un messaggio Shipment.

Per l'elenco completo delle proprietà in Shipment, consulta la documentazione di riferimento.

Esempio di Shipment

In questo esempio, hai un servizio di asilo per cani in cui ritiri i cani da casa loro e li porti al tuo asilo. Vuoi impostare la località di ritiro di due cani e impostare la località di consegna presso la tua attività:

• La casa del primo cane si trova a Coit Tower, San Francisco. Le coordinate di questa località sono latitudine 37.8024 e longitudine -122.4058.
• La casa del secondo cane si trova nel South Sunset Playground Park, San Francisco. Le coordinate di questa località sono latitudine 37.7359 e longitudine -122.5011.
• Il tuo asilo per cani si trova nel Mission Dolores Park, San Francisco. Le coordinate di questa località sono latitudine 37.759773 e longitudine -122.427063.

Di seguito è riportato un esempio di codice di un Shipment messaggio, in cui l'shipments oggetto contiene due tipi di messaggi Shipmentcon le coordinate di esempio.

{
  "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

Il tipo di messaggio Vehicle definisce la struttura delle proprietà di un veicolo che può eseguire una spedizione in un percorso.

Come illustrato nel diagramma:

• Un messaggio Vehicle contiene tutte le informazioni di un veicolo reale.
• Tutti i messaggi Vehicle sono specificati nel campo vehicles.
• Il campo vehicles contiene più messaggi Vehicle.

La tabella seguente descrive alcune proprietà pertinenti di un Vehicle.

Esempio di Vehicle

In questo esempio, hai un servizio di asilo per cani e vuoi definire la posizione del tuo veicolo all'inizio e alla fine della giornata e la quantità di carburante che consuma. Non devi specificare l'orario di lavoro del veicolo perché corrispondono alle ore definite nelle proprietà globalStartTime e globalEndTime all'interno dell'oggetto ShipmentModel.

Per questo esempio, i valori delle proprietà Vehicle nella richiesta sono i seguenti:

Di seguito è riportato un esempio di codice di un Vehicle messaggio che incorpora i valori dello scenario di esempio.

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

Per l'elenco completo delle proprietà in Vehicle, consulta la documentazione di riferimento.

Esempio di richiesta completa

L'esempio di codice seguente fornisce un esempio di richiesta completa, che combina gli esempi di ShipmentModel, Shipment e Vehicle mostrati in questo documento.

{
  "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"
  }
}