Estructura base (ShipmentModel, Shipment y Vehicle)

ShipmentModel tiene un objeto "shipments" con un tipo de mensaje "Shipment" y un objeto "vehicles" con un tipo de mensaje "Vehicle".

El objetivo de la API de Route Optimization es planificar rutas para una flota de vehículos que visiten un conjunto de ubicaciones. El objeto OptimizeToursRequest describe las propiedades de estos vehículos y ubicaciones, y es la estructura principal del cuerpo de la solicitud de cada extremo.

La estructura base del objeto OptimizeToursRequest es la siguiente:

En este documento, se describen los siguientes tipos de mensajes:

  • ShipmentModel: Contiene la lista de envíos, los vehículos disponibles y otros objetos que describen sus relaciones.
  • Shipment: Describe las ubicaciones que debe visitar un vehículo. Pueden representar paquetes reales para recoger y entregar, o lugares donde el conductor del vehículo realiza un servicio.
  • Vehicle: Describe el medio de transporte entre las ubicaciones de envío. Cada vehículo corresponde a un vehículo real o a una persona que se desplaza a pie.

ShipmentModel

ShipmentModel contiene los elementos del problema de optimización de rutas. Incluye un conjunto de envíos que pueden realizar un conjunto de vehículos, teniendo en cuenta las restricciones y minimizando el costo general.

En la siguiente tabla, se describen algunas propiedades relevantes de ShipmentModel:

Propiedades Descripción
shipments y vehicles Objetos obligatorios que contienen los detalles de uno o varios envíos y vehículos.
globalStartTime y globalEndTime Indica el inicio y el final del período en el que todos los vehículos deben completar todos los envíos. Si bien estas propiedades no son obligatorias, se recomienda incluirlas , ya que el optimizador funciona mejor cuando se respetan las restricciones de tiempo.

Consulta la documentación de referencia para obtener la lista completa de las propiedades de ShipmentModel.

Ejemplo de ShipmentModel

En este ejemplo, tienes un servicio de guardería para perros y estás comenzando a crear tu solicitud. Definirás los envíos y los vehículos más adelante, pero quieres comenzar por establecer tu horario de atención y el costo operativo por hora.

Para este ejemplo, los valores de las propiedades ShipmentModel de tu solicitud son los siguientes:

Propiedad Valor Descripción
globalStartTime 2024-02-13T00:00:00.000Z La fecha y hora de inicio del horario de atención.
globalEndTime 2024-02-14T06:00:00.000Z La fecha y hora de finalización del horario de atención.

El siguiente es un ejemplo de código de un ShipmentModel mensaje que incorpora los valores de la situación de ejemplo.

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

Shipment

El tipo de mensaje Shipment define la estructura de propiedades de un envío que se puede entregar o un servicio que se puede realizar en una ruta.

Un envío real equivale a un mensaje `Shipment`, que se incluye en un objeto `shipments`.

Como se ilustra en el diagrama:

Un mensaje Shipment requiere al menos un objeto pickups o deliveries. La definición de estos objetos es la siguiente:

  • pickups define la ubicación de recolección de un envío.
  • deliveries define la ubicación de entrega de un envío.
  • Tanto pickups como deliveries contienen un tipo de mensaje VisitRequest que define ubicaciones y otros detalles.

En la siguiente tabla, se describen las diferentes situaciones según la configuración de pickups y deliveries en un mensaje Shipment.

Situación Descripción
pickups únicamente Se supone que solo recolectas el envío.
deliveries únicamente Se supone que precargaste el envío o que entregas un servicio.
Tanto pickups como deliveries El vehículo asignado debe completar primero la recolección y, luego, la entrega. Solo el vehículo que realizó la recolección puede realizar la entrega.
Varias pickups o deliveries Si un envío incluye varias posibilidades para pickups o deliveries, el optimizador elige una opción de recolección y una opción de entrega para usar, según la minimización de costos y el cumplimiento de las restricciones.

Consulta la documentación de referencia para obtener la lista completa de las propiedades de Shipment.

Ejemplo de Shipment

En este ejemplo, tienes un servicio de guardería para perros en el que recoges perros de sus casas y los llevas a tu guardería. Quieres establecer la ubicación de recolección de dos perros y establecer su ubicación de entrega en tu empresa:

  • La casa del primer perro está en la torre Coit, San Francisco. Las coordenadas de esta ubicación son latitud 37.8024 y longitud -122.4058.
  • La casa del segundo perro está en el parque South Sunset Playground, San Francisco. Las coordenadas de esta ubicación son latitud 37.7359 y longitud -122.5011.
  • Tu guardería para perros está en el parque Mission Dolores, San Francisco. Las coordenadas de esta ubicación son latitud 37.759773 y longitud -122.427063.

El siguiente es una muestra de código de un Shipment mensaje, en el que el shipments objeto contiene dos Shipmenttipos de mensajes con las coordenadas de ejemplo.

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

El tipo de mensaje Vehicle define la estructura de propiedades de un vehículo que puede realizar un envío en una ruta.

Un vehículo real equivale a un mensaje `Vehicle`, que se incluye en un objeto `vehicles`.

Como se ilustra en el diagrama:

  • Un mensaje Vehicle tiene toda la información de un vehículo real.
  • Todos los Vehicle mensajes se especifican en el campo vehicles.
  • El vehicles campo contiene varios Vehicle mensajes.

En la siguiente tabla, se describen algunas propiedades relevantes de un Vehicle.

Propiedades Descripción
startLocation y endLocation La ubicación de inicio y finalización de los vehículos, que forman parte de la ruta optimizada final. Si no se definen, se establecen de forma predeterminada en las ubicaciones de recolección del primer envío y de entrega del último envío.
costPerHour, costPerKilometer, costPerTraveledHour Parámetros de costo específicos del vehículo. Se recomienda que tengas al menos un parámetro de costo en tu solicitud para que la API muestre una ruta optimizada. Consulta el concepto clave del modelo de costos para obtener más información sobre los costos.
startTimeWindows y endTimeWindows Definen los períodos en los que un vehículo puede operar en una ruta. Estos deben estar dentro del período globalStartTime y globalEndTime establecido en ShipmentModel. Si bien esta propiedad no es obligatoria, se recomienda incluirla , ya que el optimizador funciona mejor cuando se respetan las restricciones de tiempo.

Ejemplo de Vehicle

En este ejemplo, tienes un servicio de guardería para perros y quieres definir la ubicación de tu vehículo al comienzo y al final del día, y cuánto combustible gasta. No es necesario que especifiques el horario laboral del vehículo porque coincide con las horas que definiste en las propiedades globalStartTime y globalEndTime dentro del objeto ShipmentModel.

Para este ejemplo, los valores de las propiedades Vehicle de tu solicitud son los siguientes:

Propiedad Valor Descripción
startLocation latitude: 37.759773, longitude: -122.427063 Las coordenadas de inicio de la ruta para tu vehículo. Coinciden con la ubicación de tu guardería para perros, que se encuentra en el parque Mission Dolores, San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Las coordenadas de finalización de la ruta para tu vehículo. Coinciden con la ubicación de tu guardería para perros, que se encuentra en el parque Mission Dolores, San Francisco.
costPerHour 27 Cuánto le pagas a un conductor por conducir tu vehículo de guardería para perros. Le pagas al conductor 27 dólares por hora.

El siguiente es un ejemplo de código de un Vehicle mensaje que incorpora los valores de la situación de ejemplo.

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

Consulta la documentación de referencia para obtener la lista completa de las propiedades de Vehicle.

Ejemplo de solicitud completa

En la siguiente muestra de código, se proporciona un ejemplo de solicitud completa, que combina los ejemplos de ShipmentModel, Shipment y Vehicle que se muestran en este 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"
  }
}