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 un vehículo debe visitar. 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 mueve 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 se consideran las restricciones y se 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, te recomendamos que las incluyas, 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 empezando a crear tu solicitud. Definirás los envíos y los vehículos más adelante, pero primero debes 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 Es la fecha y hora de inicio del horario de atención.
globalEndTime 2024-02-14T06:00:00.000Z Es la fecha y hora de finalización del horario de atención.

La siguiente es una muestra 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 la propiedad de un envío que se puede entregar o el servicio que se puede realizar en una ruta.

Un envío real equivale a un mensaje "Shipment", que se encuentra dentro de un objeto "shipments".

Como se ilustra en el diagrama:

Un mensaje Shipment requiere al menos uno de los objetos 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 da por sentado que solo recogerás el envío.
deliveries únicamente Se supone que cargaste el envío por adelantado o que estás realizando una entrega de 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 enumera 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 minimizar el costo y cumplir con 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 recoges a los perros de su casa y los llevas a tu guardería. Quieres establecer la ubicación de retiro de dos perros y su ubicación de entrega en tu empresa:

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

El siguiente es 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 propiedad de un vehículo que puede realizar un envío en una ruta.

Un vehículo real equivale a un mensaje "Vehicle", que se encuentra dentro de 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 recogida y entrega del primer y último envío.
costPerHour, costPerKilometer, costPerTraveledHour Parámetros de costo específicos del vehículo. Se recomienda que tengas al menos uno parámetro de costo en tu solicitud para que la API muestre 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 globalStartTime y globalEndTime establecido en ShipmentModel. Si bien esta propiedad no es obligatoria, te recomendamos que la incluyas, 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 principio y al final del día, y la cantidad de combustible que consume. No es necesario que especifiques el horario laboral del vehículo, ya que coincide con las horas 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 Las coordenadas iniciales de la ruta de tu vehículo. Coinciden con la ubicación de la guardería para perros, que se encuentra en Mission Dolores Park, San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Las coordenadas de destino de la ruta de tu vehículo Coinciden con la ubicación de la guardería para perros, que se encuentra en Mission Dolores Park, San Francisco.
costPerHour 27 El importe que le pagas a un conductor por conducir el vehículo de la guardería para perros. Le pagas al conductor 27 dólares por hora.

La siguiente es una muestra 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 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"
  }
}