Estrutura básica (ShipmentModel, Shipment e Vehicle)

O ShipmentModel tem um objeto "shipments" com um tipo de mensagem "Shipment" e um objeto "vehicles" com um tipo de mensagem "Vehicle".

O objetivo da API Route Optimization é planejar rotas para uma frota de veículos visitarem um conjunto de locais. O objeto OptimizeToursRequest descreve as propriedades desses veículos e locais e é a estrutura principal do corpo da solicitação de cada endpoint.

A estrutura básica do objeto OptimizeToursRequest é a seguinte:

Este documento descreve os seguintes tipos de mensagem:

  • ShipmentModel: contém a lista de remessas, veículos disponíveis e outros objetos que descrevem as relações entre eles.
  • Shipment: descreve os locais que serão visitados por um veículo. Elas podem representar pacotes reais para retirada e entrega ou locais onde o motorista do veículo realiza um serviço.
  • Vehicle: descreve o meio de transporte entre os locais de envio. Cada veículo corresponde a um veículo real ou a uma pessoa se deslocando a pé.

ShipmentModel

ShipmentModel contém os elementos do problema de otimização de rotas. Ele contém um conjunto de remessas que podem ser realizadas por um conjunto de veículos, considerando restrições e minimizando o custo geral.

A tabela abaixo descreve algumas propriedades relevantes de ShipmentModel:

Propriedades Descrição
shipments e vehicles Objetos obrigatórios que contêm os detalhes de uma ou várias entregas e veículos.
globalStartTime e globalEndTime Indica o início e o fim do período em que todos os veículos precisam concluir todas as entregas. Embora essas propriedades não sejam obrigatórias, recomendamos incluí-las, já que o otimizador funciona melhor quando segue restrições de tempo.

Consulte a documentação de referência para ver a lista completa das propriedades em ShipmentModel.

Exemplo da função ShipmentModel

Neste exemplo, você tem um serviço de creche para cachorros e está começando a criar sua solicitação. Você vai definir as entregas e os veículos mais tarde, mas quer começar definindo o horário de funcionamento e o custo operacional por hora.

Neste exemplo, os valores da propriedade ShipmentModel na sua solicitação são os seguintes:

Propriedade Valor Descrição
globalStartTime 2024-02-13T00:00:00.000Z A data e hora de início do horário de funcionamento.
globalEndTime 2024-02-14T06:00:00.000Z A data e a hora de término do horário de funcionamento.

Veja a seguir um exemplo de código de uma mensagem ShipmentModel que incorpora os valores do cenário de exemplo.

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

Shipment

O tipo de mensagem Shipment define a estrutura de propriedade de uma remessa que pode ser entregue ou de um serviço que pode ser realizado em um trajeto.

Uma remessa real equivale a uma mensagem `Shipment`, que está contida em um objeto `shipments`.

Conforme ilustrado no diagrama:

  • Uma mensagem Shipment tem todas as informações de uma remessa ou um serviço real.
  • Todas as mensagens Shipment são especificadas no campo shipments.
  • O campo shipments contém uma ou mais mensagens Shipment.

Uma mensagem Shipment requer pelo menos um objeto pickups ou deliveries. A definição desses objetos é a seguinte:

A tabela a seguir descreve os diferentes cenários com base na configuração de pickups e deliveries em uma mensagem Shipment.

Cenário Descrição
Somente pickups Presume-se que você esteja apenas coletando a remessa.
Somente deliveries Presume-se que você tenha pré-carregado a remessa ou esteja prestando um serviço.
pickups e deliveries O veículo atribuído precisa concluir primeiro a retirada e depois a entrega. Somente o veículo que fez a retirada pode fazer a entrega.
Vários pickups ou deliveries Se uma remessa listar várias possibilidades para pickups ou deliveries, o otimizador escolherá uma opção de retirada e uma de entrega para usar, com base na minimização de custos e no cumprimento das restrições.

Consulte a documentação de referência para ver a lista completa das propriedades em Shipment.

Exemplo da função Shipment

Neste exemplo, você tem um serviço de creche para cachorros em que busca os animais na casa deles e os leva para a creche. Você quer definir o local de retirada de dois cachorros e o local de entrega para sua empresa:

  • A casa do primeiro cachorro fica na Coit Tower, em São Francisco. As coordenadas desse local são latitude 37.8024 e longitude -122.4058.
  • A casa do segundo cachorro fica no South Sunset Playground Park, em São Francisco. As coordenadas desse local são latitude 37.7359 e longitude -122.5011.
  • Sua creche para cachorros fica no Mission Dolores Park, em São Francisco. As coordenadas desse local são latitude 37.759773 e longitude -122.427063.

Veja a seguir um exemplo de código de uma mensagem Shipment, em que o objeto shipments contém dois tipos de mensagem Shipment com as coordenadas de exemplo.

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

O tipo de mensagem Vehicle define a estrutura de propriedade de um veículo que pode realizar uma entrega em um trajeto.

Um veículo real equivale a uma mensagem "Vehicle", que está contida em um objeto "vehicles".

Conforme ilustrado no diagrama:

  • Uma mensagem Vehicle tem todas as informações de um veículo real.
  • Todas as mensagens Vehicle são especificadas no campo vehicles.
  • O campo vehicles contém várias mensagens Vehicle.

A tabela a seguir descreve algumas propriedades relevantes de um Vehicle.

Propriedades Descrição
startLocation e endLocation Os locais de início e término dos veículos, que fazem parte do trajeto otimizado final. Se não forem definidos, o padrão será os locais da primeira coleta e da última entrega.
costPerHour, costPerKilometer, costPerTraveledHour Parâmetros de custo específicos do veículo. Recomendamos que você tenha pelo menos um parâmetro de custo na solicitação para que a API retorne um trajeto otimizado. Consulte o conceito principal Modelo de custo para saber mais sobre os custos.
startTimeWindows e endTimeWindows Defina os períodos em que um veículo pode operar em um trajeto. Eles precisam estar dentro do período de globalStartTime e globalEndTime definido em ShipmentModel. Embora essa propriedade não seja obrigatória, recomendamos incluí-la, já que o otimizador funciona melhor quando segue restrições de tempo.

Exemplo da função Vehicle

Neste exemplo, você tem um serviço de creche para cachorros e quer definir a localização do seu veículo no início e no fim do dia, além de quanto combustível ele gasta. Não é necessário especificar o horário de trabalho do veículo porque ele corresponde ao horário definido nas propriedades globalStartTime e globalEndTime no objeto ShipmentModel.

Neste exemplo, os valores da propriedade Vehicle na sua solicitação são os seguintes:

Propriedade Valor Descrição
startLocation latitude: 37.759773, longitude: -122.427063 As coordenadas iniciais do trajeto do seu veículo. Eles correspondem ao local da sua creche para cães, que fica no Mission Dolores Park, em São Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 As coordenadas finais do trajeto do seu veículo. Eles correspondem ao local da sua creche para cães, que fica no Mission Dolores Park, em São Francisco.
costPerHour 27 Quanto você paga a um motorista para dirigir o veículo da sua creche para cachorros. Você paga US$ 27 por hora ao motorista.

Veja a seguir um exemplo de código de uma mensagem Vehicle que incorpora os valores do cenário de exemplo.

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

Consulte a documentação de referência para ver a lista completa das propriedades em Vehicle.

Exemplo de solicitação completa

O exemplo de código a seguir fornece um exemplo de solicitação completo, combinando os exemplos de ShipmentModel, Shipment e Vehicle mostrados neste 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"
  }
}