Estrutura básica (ShipmentModel, Shipment e Vehicle)

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 trajetos para uma frota de veículos 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 de base do objeto OptimizeToursRequest é a seguinte:

Este documento descreve os seguintes tipos de mensagem:

  • ShipmentModel: contém a lista de envios, veículos disponíveis e outros objetos que descrevem os relacionamentos.
  • Shipment: descreve os locais a serem visitados por um veículo. Eles podem representar pacotes reais para coleta e entrega ou lugares em que 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 que se desloca 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 as 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 todos os envios. Embora essas propriedades não sejam obrigatórias, recomendamos incluí-las porque o otimizador funciona melhor quando segue as restrições de tempo.

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

Exemplo de ShipmentModel

Neste exemplo, você tem um serviço de creche para cães e está começando a criar sua solicitação. Você vai definir 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 ShipmentModel valores da propriedade 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 de funcionamento.
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 propriedade de um envio que pode ser entregue ou 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 Shipment mensagem requer pelo menos um pickups ou deliveries objeto. 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
pickups somente Supõe-se que você esteja apenas coletando o envio.
deliveries somente Supõe-se que você tenha pré-carregado o envio ou esteja entregando um serviço.
pickups e deliveries O veículo atribuído precisa concluir a coleta primeiro 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 de pickups ou deliveries, o otimizador escolhe uma opção de coleta e uma opção 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 das propriedades em Shipment.

Exemplo de Shipment

Neste exemplo, você tem um serviço de creche para cães em que busca os cães na casa deles e os entrega na creche. Você quer definir o local de coleta de dois cães e definir o local de entrega para sua empresa:

  • A casa do primeiro cão 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 cão 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 cães 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 shipments objeto contém dois tipos de mensagem Shipmentcom 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 um envio em um trajeto.

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

Conforme ilustrado no diagrama:

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

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, eles serão definidos como 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. Recomendamos que você tenha pelo menos um parâmetro de custo na sua solicitação para que a API retorne um trajeto otimizado. Consulte o conceito principal do 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 globalStartTime e globalEndTime definido em ShipmentModel. Embora essa propriedade não seja obrigatória, recomendamos incluí-la porque o otimizador funciona melhor quando segue as restrições de tempo.

Exemplo de Vehicle

Neste exemplo, você tem um serviço de creche para cães e quer definir o local do veículo no início e no fim do dia e quanto gás ele gasta. Não é necessário especificar o horário de funcionamento do veículo porque ele corresponde às horas definidas nas propriedades globalStartTime e globalEndTime no objeto ShipmentModel.

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

Propriedade Valor Descrição
startLocation latitude: 37.759773, longitude: -122.427063 As coordenadas de início do trajeto do veículo. Elas 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 de término do trajeto do veículo. Elas 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 creche para cães. Você paga ao motorista 27 dólares 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 das propriedades em Vehicle.

Exemplo de solicitação completa

O exemplo de código a seguir mostra uma solicitação completa, combinando os ShipmentModel, Shipment e Vehicle exemplos 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"
  }
}