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 que vão visitar 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 mensagens:

  • ShipmentModel:contém a lista de envios, veículos disponíveis e outros objetos que descrevem os relacionamentos entre eles.
  • Shipment:descreve os locais a serem visitados por um veículo. Eles podem representar pacotes reais para coleta 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 movendo a pé.

ShipmentModel

ShipmentModel contém os elementos do problema de otimização de rotas. Ele contém um conjunto de envios que podem ser realizados 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 um ou vários envios 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, é recomendável incluí-las, já que o otimizador funciona melhor quando respeita as restrições de tempo.

Consulte a documentação de referência para conferir a lista completa de 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 os envios e veículos mais tarde, mas quer começar definindo o horário de funcionamento e o custo operacional por hora.

Para este 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 a hora de início do horário comercial.
globalEndTime 2024-02-14T06:00:00.000Z A data e a hora de término do horário de funcionamento.

Confira 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 propriedades de uma entrega que pode ser feita ou um serviço que pode ser realizado em um trajeto.

Uma remessa real é igual a uma mensagem "Shipment", que está contida em um objeto "shipments".

Conforme ilustrado no diagrama:

  • Uma mensagem de Shipment tem todas as informações de um envio ou serviço real.
  • Todas as mensagens Shipment são especificadas no campo shipments.
  • O campo shipments contém uma ou várias 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ê está apenas retirando a encomenda.
Somente deliveries Presumimos que você pré-carregou o envio ou está entregando um serviço.
pickups e deliveries O veículo atribuído precisa primeiro fazer a coleta e depois a entrega. Somente o veículo que fez a coleta pode fazer a entrega.
Vários pickups ou deliveries Se um envio listar várias possibilidades para pickups ou deliveries, o otimizador escolherá uma opção de coleta e uma de entrega para usar, com base na minimização de custos e no atendimento às restrições.

Consulte a documentação de referência para conferir a lista completa de 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 primeira casa do cachorro fica na Coit Tower, em São Francisco. As coordenadas desse local são latitude 37.8024 e longitude -122.4058.
  • A segunda casa do 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.

Confira 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 propriedades de um veículo que pode fazer uma entrega em um trajeto.

Um veículo real é igual 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 O local de início e término dos veículos, que fazem parte do trajeto otimizado final. Se não forem definidos, os padrões serão os locais de coleta do primeiro envio e de entrega do último envio.
costPerHour, costPerKilometer, costPerTraveledHour Parâmetros de custo específicos do veículo. É recomendável ter pelo menos um parâmetro de custo na solicitação para que a API retorne um trajeto otimizado. Consulte o conceito-chave 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. Elas precisam estar dentro da janela de tempo globalStartTime e globalEndTime definida 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 aos horários definidos nas propriedades globalStartTime e globalEndTime no objeto ShipmentModel.

Para este 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 para seu veículo. Esses resultados correspondem à localização da sua creche para cachorros, que fica no Mission Dolores Park, em São Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 As coordenadas finais do trajeto para seu veículo. Esses resultados correspondem à localização da sua creche para cachorros, que fica no Mission Dolores Park, em São Francisco.
costPerHour 27 Quanto você paga a um motorista para dirigir o veículo da creche para cachorros. Você paga ao motorista US$ 27 por hora.

Confira 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 conferir a lista completa de propriedades em Vehicle.

Exemplo de solicitação completa

O exemplo de código a seguir fornece um exemplo de solicitação completa, 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"
  }
}