Estrutura básica (ShipmentModel, Shipment e 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 básica do objeto OptimizeToursRequest é a seguinte:

• O campo model contém uma mensagem ShipmentModel com dois campos principais: campos:
  • Um campo shipments, que contém uma ou várias mensagens Shipment.
  • Um campo vehicles, que contém uma ou várias mensagens Vehicle.

Este documento descreve os seguintes tipos de mensagem:

• ShipmentModel: contém a lista de remessas, 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 presta um serviço.
• Vehicle: descreve o meio de transporte entre os locais de remessa. 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 remessas que podem ser realizadas por um conjunto de veículos, considerando as restrições e minimizando o custo geral.

A tabela abaixo descreve algumas propriedades relevantes de ShipmentModel:

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 remessas 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:

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 uma remessa que pode ser entregue ou um serviço que pode ser realizado em um trajeto.

Conforme ilustrado no diagrama:

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

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

• pickups define o local de retirada de um envio.
• deliveries define o local de entrega de uma remessa.
• Tanto pickups quanto deliveries contêm um tipo de mensagem VisitRequest que define locais e outros detalhes.

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

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 sua 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 uma remessa em um trajeto.

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.

Exemplo de Vehicle

Neste exemplo, você tem um serviço de creche para cães e quer definir o local do seu 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 trabalho 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:

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