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'obiettivo dell'API Route Optimization è pianificare i percorsi per una flotta di veicoli in modo che visitino 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:

Questo documento descrive i seguenti tipi di messaggi:

  • ShipmentModel: contiene l'elenco delle spedizioni, dei veicoli disponibili e di altri oggetti che descrivono le relative 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 località di spedizione. Ogni veicolo corrisponde a un veicolo reale o a una persona che si muove 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 al 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 nido per cani e stai iniziando a elaborare la tua richiesta. Definirai 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 un percorso.

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

Come illustrato nel diagramma:

  • Un messaggio Shipment contiene tutte le informazioni di una spedizione o 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 che 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.

Scenario Descrizione
Solo pickups Si presume che tu stia solo ritirando la spedizione.
Solo deliveries Si presume che tu abbia precaricato la spedizione o stia gestendo la consegna di un servizio.
Sia pickups che deliveries Il veicolo assegnato deve completare prima il ritiro e poi la consegna. Solo il veicolo che ha effettuato il ritiro può effettuare la consegna.
Più pickups o deliveries Se una spedizione elenca più possibilità per pickups o deliveries, l'ottimizzatore sceglie un'opzione di ritiro e un'opzione di consegna da utilizzare, in base alla minimizzazione 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 raccogli i cani dalla loro casa e li consegni all'asilo. Vuoi impostare la località di ritiro di due cani e la località di consegna nella tua attività:

  • La prima casa per cani si trova nella Coit Tower di San Francisco. Le coordinate di questa località 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 località sono latitudine 37,7359 e longitudine -122,5011.
  • La tua pensione diurna per cani si trova a Mission Dolores Park, a San Francisco. Le coordinate di questa località 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 messaggi 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 delle proprietà di un veicolo che può eseguire una spedizione in un percorso.

Un veicolo reale corrisponde a un messaggio "Vehicle", che è 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 Le posizioni di partenza e di arrivo dei veicoli, che fanno parte del percorso ottimizzato finale. Se non sono definiti, per impostazione predefinita vengono utilizzati i luoghi di ritiro della prima spedizione e di consegna dell'ultima spedizione.
costPerHour, costPerKilometer, costPerTraveledHour Parametri di costo specifici del veicolo. Ti consigliamo di avere 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 costo.
startTimeWindows e endTimeWindows Definisci gli intervalli di tempo in cui un veicolo può operare su un percorso. Devono rientrare nella finestra temporale compresa tra globalStartTime e globalEndTime impostata in ShipmentModel. Sebbene questa proprietà non sia obbligatoria, è consigliabile includerla poiché l'ottimizzatore funziona meglio se 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 carburante che consuma. Non è necessario specificare l'orario di lavoro del veicolo perché corrisponde alle ore che hai 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. Corrispondono alla località della tua pensione diurna per cani, che si trova nel parco Mission Dolores a San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Le coordinate finali del percorso per il tuo veicolo. Corrispondono alla località della tua pensione diurna per cani, che si trova nel parco Mission Dolores a San Francisco.
costPerHour 27 L'importo che paghi a un conducente per guidare il veicolo del tuo asilo per cani. Paghi il conducente 27 dollari l'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 completa

Il seguente esempio di codice fornisce un esempio di richiesta completa, che combina gli esempi 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"
  }
}