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 un parco veicoli per 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:

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à che devono essere visitate da un veicolo. Possono rappresentare pacchi effettivi da ritirare e consegnare o luoghi in cui il conducente del veicolo esegue un servizio.
  • Vehicle: descrive i mezzi 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 dei percorsi. 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, ti consigliamo di includerle, poiché l'ottimizzatore funziona meglio quando 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. Definirai le spedizioni e i veicoli in un secondo momento, ma vuoi iniziare impostando l'orario di apertura e i costi operativi orari.

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 delle proprietà di una spedizione che può essere consegnata o di un servizio che può essere eseguito su un percorso.

Una spedizione reale equivale a un messaggio "Shipment", contenuto all'interno di un oggetto "shipments"

Come illustrato nel diagramma:

  • Un messaggio Shipment contiene tutte le informazioni di una spedizione o di un servizio reali.
  • 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 che tu stia fornendo un servizio.
Sia pickups che deliveries Il veicolo assegnato deve completare prima il ritiro, 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, l'ottimizzatore 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 per cani in cui vai a prendere i cani a 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 nella Coit Tower, a 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.
  • La tua pensione 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 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 delle proprietà di un veicolo che può eseguire una spedizione in un percorso.

Un veicolo reale equivale a un messaggio "Vehicle", contenuto all'interno di 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 definite, per impostazione predefinita vengono utilizzate le località del primo ritiro e dell'ultima consegna della spedizione.
costPerHour, costPerKilometer e costPerTraveledHour Parametri di costo specifici del 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 costo.
startTimeWindows e endTimeWindows Definisci i periodi di tempo in cui un veicolo può operare su un percorso. Questi devono rientrare nella finestra temporale globalStartTime e globalEndTime impostata in ShipmentModel. Sebbene questa proprietà non sia obbligatoria, ti consigliamo di includerla, poiché l'ottimizzatore funziona meglio quando rispetta i vincoli di tempo.

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 è 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 località della tua pensione per cani, che si trova a Mission Dolores Park, San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Le coordinate di arrivo del percorso per il tuo veicolo. Queste corrispondono alla località della tua pensione per cani, che si trova a Mission Dolores Park, San Francisco.
costPerHour 27 Quanto paghi un conducente per guidare il veicolo della tua attività di asilo per cani. Paghi al conducente 27 $ 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 completo, combinando 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"
  }
}