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 que una flota de vehículos visite 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 retirar 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 puede realizar un conjunto de vehículos, a la vez que considera las restricciones y minimiza el costo general.

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

Propiedades Descripción
shipments y vehicles Son 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 cumplen las restricciones de tiempo.

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

ShipmentModel Ejemplo

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 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.

A continuación, se muestra un ejemplo de código de un mensaje ShipmentModel 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 de la vida real equivale a un mensaje de "Envío", que se incluye en un objeto "envíos".

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:

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 recolectarás el envío.
deliveries únicamente Se supone que cargaste el envío con anticipación o que estás entregando un servicio.
pickups y deliveries El vehículo asignado debe completar primero el retiro y, luego, la entrega. Solo el vehículo que realizó el retiro 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 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 en Shipment.

Shipment Ejemplo

En este ejemplo, tienes un servicio de guardería para perros en el que recoges a los perros de sus casas y los llevas a tu guardería. Quieres establecer la ubicación de recogida 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 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 de la vida 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 mensajes 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 retiro del primer envío y de entrega del último envío.
costPerHour, costPerKilometer, costPerTraveledHour Parámetros de costos específicos del vehículo. Te recomendamos que incluyas 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. Estas 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.

Vehicle Ejemplo

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 la cantidad de combustible que gasta. 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 de tu vehículo. Estas coinciden con la ubicación de tu guardería para perros, que se encuentra en Mission Dolores Park, San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Son las coordenadas de finalización de la ruta de tu vehículo. Estas coinciden con la ubicación de tu guardería para perros, que se encuentra en Mission Dolores Park, San Francisco.
costPerHour 27 Cuánto le pagas a un conductor por manejar el vehículo de tu guardería para perros Le pagas al conductor 27 dólares por hora.

A continuación, se muestra un ejemplo de código de un mensaje Vehicle 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 en Vehicle.

Ejemplo de solicitud completa

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