Struttura di base (ShipmentModel, Shipment e Vehicle)

ShipmentModel ha un oggetto `shipments` con un tipo di messaggio `Shipment` e un oggetto `vehicles` con un tipo di messaggio `Vehicle`.

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

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

Questo documento descrive i seguenti tipi di messaggi:

  • ShipmentModel: contiene l'elenco delle spedizioni, dei veicoli disponibili e di altri oggetti che descrivono le loro relazioni.
  • Shipment: descrive le località da visitare con un veicolo. Possono rappresentare pacchi effettivi da ritirare e consegnare o luoghi in cui il conducente del veicolo esegue un servizio.
  • Vehicle: descrive il mezzo di trasporto tra le sedi 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:

Proprietà Descrizione
shipments e vehicles Oggetti obbligatori che contengono i dettagli di una o più spedizioni e veicoli.
globalStartTime e globalEndTime Indica l'inizio e la fine della finestra temporale in cui tutti i veicoli devono completare tutte le spedizioni. Sebbene queste proprietà non siano obbligatorie, è consigliabile includerle poiché l'ottimizzatore funziona meglio se rispetta i vincoli di tempo.

Consulta la documentazione di riferimento per l'elenco completo delle proprietà in ShipmentModel.

Esempio di ShipmentModel

In questo esempio, hai un servizio di asilo per cani e stai iniziando a creare la tua 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 della proprietà ShipmentModel nella richiesta sono i seguenti:

Proprietà Valore Descrizione
globalStartTime 2024-02-13T00:00:00.000Z La data e l'ora di inizio dell'orario di apertura.
globalEndTime 2024-02-14T06:00:00.000Z La data e l'ora di fine dell'orario di apertura.

Di seguito è riportato un esempio di codice di un messaggio ShipmentModel 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 della proprietà di una spedizione che può essere consegnata o del servizio che può essere eseguito su una route.

Una spedizione reale equivale a un messaggio "Shipment", contenuto in un oggetto "shipments".

Come illustrato nel diagramma:

  • Un messaggio Shipment contiene tutte le informazioni di una spedizione o di un servizio reale.
  • Tutti i messaggi Shipment 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 posizioni e altri dettagli.

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

Scenario Descrizione
Solo pickups Si presume che tu stia solo ritirando la spedizione.
Solo deliveries Si presume che tu abbia precaricato la spedizione o che stia fornendo un servizio.
Sia pickups che deliveries Il veicolo assegnato deve completare prima il ritiro e poi la consegna. Solo il veicolo che ha eseguito il ritiro può eseguire la consegna.
Più pickups o deliveries Se una spedizione elenca più possibilità per pickups o deliveries, lo strumento di ottimizzazione sceglie un'opzione di ritiro e un'opzione di consegna da utilizzare, in base alla riduzione dei costi e al rispetto dei vincoli.

Consulta la documentazione di riferimento per l'elenco completo delle proprietà in Shipment.

Esempio di Shipment

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

  • La prima casa del cane si trova nella Coit Tower, a San Francisco. Le coordinate di questa posizione sono latitudine 37.8024 e longitudine -122.4058.
  • La seconda casa del cane si trova nel South Sunset Playground Park di San Francisco. Le coordinate di questa posizione sono latitudine 37.7359 e longitudine -122.5011.
  • La tua pensione diurna per cani si trova nel Mission Dolores Park, a San Francisco. Le coordinate di questa posizione sono latitudine 37.759773 e longitudine -122.427063.

Di seguito è riportato un esempio di codice di un messaggio Shipment, in cui l'oggetto shipments contiene due tipi di messaggio Shipment con 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 della proprietà di un veicolo che può eseguire una spedizione in un percorso.

Un veicolo reale equivale a un messaggio "Vehicle", contenuto in un oggetto "vehicles"

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.

Proprietà Descrizione
startLocation e endLocation La posizione di partenza e di arrivo dei veicoli, che fanno parte del percorso ottimizzato finale. Se non sono definiti, vengono impostati per impostazione predefinita sulle località di ritiro della prima spedizione e di consegna dell'ultima spedizione.
costPerHour, costPerKilometer, costPerTraveledHour Parametri di costo specifici per il veicolo. Ti consigliamo di includere almeno un parametro di costo nella richiesta affinché l'API restituisca un percorso ottimizzato. Per saperne di più sui costi, consulta il concetto chiave Modello di costi.
startTimeWindows e endTimeWindows Definisci i periodi di tempo in cui un veicolo può operare su un percorso. Questi devono rientrare nella finestra temporale compresa tra le ore globalStartTime e le ore globalEndTime impostate in ShipmentModel. Sebbene questa proprietà non sia obbligatoria, è consigliabile includerla poiché l'ottimizzatore funziona meglio quando rispetta i vincoli di tempo.

Esempio di Vehicle

In questo esempio, hai un servizio di asilo nido per cani e vuoi definire la posizione del tuo veicolo all'inizio e alla fine della giornata e la quantità di benzina che consuma. Non è necessario specificare l'orario di lavoro del veicolo perché corrisponde all'orario definito nelle proprietà globalStartTime e globalEndTime all'interno dell'oggetto ShipmentModel.

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

Proprietà Valore Descrizione
startLocation latitude: 37.759773, longitude: -122.427063 Le coordinate di partenza del percorso per il tuo veicolo. Queste corrispondono alla posizione della tua pensione diurna per cani, che si trova nel Mission Dolores Park, a San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Le coordinate finali del percorso per il tuo veicolo. Queste corrispondono alla posizione della tua pensione diurna per cani, che si trova nel Mission Dolores Park, a San Francisco.
costPerHour 27 Quanto paghi un autista per guidare il veicolo del tuo asilo nido per cani. Paghi l'autista 27 dollari all'ora.

Di seguito è riportato un esempio di codice di un messaggio Vehicle 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
      }
    ]
  }
}

Consulta la documentazione di riferimento per l'elenco completo delle proprietà in Vehicle.

Esempio di richiesta completo

Il seguente esempio di codice fornisce un esempio di richiesta completo, combinando 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"
  }
}