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 deben visitar 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 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 los medios 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. Contiene un conjunto de envíos que pueden realizarse con 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 en 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.

En este ejemplo, los valores de la propiedad ShipmentModel en tu solicitud son los siguientes:

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

A continuación, se muestra una muestra de código de un mensaje ShipmentModel que incorpora los valores del escenario 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 de Shipment contiene toda la información de un envío o servicio real.
  • Todos los mensajes de Shipment se especifican en el campo shipments.
  • El campo shipments contiene uno o varios mensajes Shipment.

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

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

Situación Descripción
pickups únicamente Se supone que solo retirarás el envío.
deliveries únicamente Se supone que ya precargaste el envío o que entregas un servicio.
pickups y 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.
Múltiples pickups o deliveries Si un envío incluye varias posibilidades para pickups o deliveries, el optimizador elige una opción de retiro y una opción de entrega para usar, en función de 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 en Shipment.

Ejemplo de Shipment

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

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

A continuación, se muestra un ejemplo de código de un mensaje Shipment, en el que el objeto shipments contiene dos tipos de mensajes Shipment 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 contiene toda la información de un vehículo real.
  • Todos los mensajes de Vehicle se especifican en el campo vehicles.
  • El campo vehicles contiene varios mensajes Vehicle.

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 la primera recolección y la última entrega del envío.
costPerHour, costPerKilometer, costPerTraveledHour Parámetros de costos específicos del vehículo. Se recomienda que tengas al menos un parámetro de costo en tu solicitud para que la API devuelva una ruta optimizada. Consulta el concepto clave Modelo de costos para obtener más información sobre los costos.
startTimeWindows y endTimeWindows Define los períodos en los que un vehículo puede operar en una ruta. Estos deben estar dentro del período de 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 deseas definir la ubicación de tu vehículo al comienzo y al final del día, y cuánto combustible consume. No es necesario que especifiques el horario laboral del vehículo, ya que coincide con el horario que definiste en las propiedades globalStartTime y globalEndTime dentro del objeto ShipmentModel.

En este ejemplo, los valores de la propiedad Vehicle en tu solicitud son los siguientes:

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

A continuación, se muestra una muestra de código de un mensaje Vehicle que incorpora los valores del escenario 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 en Vehicle.

Ejemplo de solicitud completa

En el siguiente ejemplo de código, se proporciona un ejemplo de solicitud completo 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"
  }
}