Сделайте свой первый запрос на оптимизацию маршрута

Разработчики Европейской экономической зоны (ЕЭЗ)

Если ваш платёжный адрес находится в Европейской экономической зоне, то с 8 июля 2025 года к использованию вами Сервисов будут применяться Условия предоставления услуг платформы Google Карт для ЕЭЗ . Функциональность сервиса зависит от региона. Подробнее .

В этом документе показано, как сделать первый запрос к API оптимизации маршрутов, используя реальный сценарий использования.

Для простоты в примере используются HTTP и JSON для демонстрации REST API. Однако для вашей рабочей среды рекомендуется использовать gRPC из-за его высокой производительности. Однако gRPC требует установки. Подробнее см. в разделе «Клиентские библиотеки API оптимизации маршрутов» .

Сценарий

Вы управляете службой дневного пребывания для собак в Сан-Франциско, работающей с 7:00 до 19:00. Сегодня утром вам нужно забрать двух собак из разных мест города. Оба владельца собак указали время для забора с 7:30 до 9:30.

У вас есть один фургон для работы, и вы платите водителю 27 долларов в час. Водитель и фургон начинают работу в вашем детском саду в 7:00 утра и должны вернуться после утренней раздачи детей к 12:00 на обеденный перерыв.

Сегодня 13 февраля 2024 года, и водителю предстоит выполнить следующие задачи:

• Возьмите бернского зенненхунда возле башни Койт.
• Заберите чихуахуа в парке South Sunset Playground.
• Отдайте обеих собак в центр дневного пребывания для собак в парке Mission Dolores.

Вам нужен маршрут, который сведет к минимуму время пребывания собак в фургоне, но при этом позволит удовлетворить требования по посадке и высадке.

Прежде чем начать

Чтобы запустить код в этом примере сценария, необходимо сначала выполнить инструкции в разделе Настройка API оптимизации маршрута .

1. Выберите подход к оптимизации маршрута

API оптимизации маршрутов предоставляет вам на выбор несколько методов в зависимости от сложности вашей задачи оптимизации.

Поскольку этот сценарий ухода за собаками представляет собой небольшой и простой запрос, используйте блокирующий метод, например optimizeTours , который быстро выдаёт результаты для небольших запросов. Подробнее о методах API оптимизации маршрутов см. в разделе Синхронные и асинхронные конечные точки .

Используйте следующий URL-адрес для создания HTTP-запроса POST к методу optimizeTours :

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Вам также необходимо установить короткие параметры времени ожидания и крайнего срока, чтобы сократить ненужное время ожидания. В этом сценарии с собачьим детским садом оптимизатору не требуется много времени для ответа на ваш запрос, поэтому используйте следующие настройки:

• Установите параметр timeout на 2 секунды.
• Оставьте настройки крайнего срока по умолчанию, которые составляют 60 секунд для запросов REST.

Важно: для других типов запросов необходимо задать настройки времени ожидания и крайнего срока в зависимости от сложности запроса, метода и выбранного протокола. Подробнее см. в разделе Время ожидания и крайние сроки .

2. Составьте тело сообщения-запроса.

После выбора метода блокировки optimizeTours и определения настроек времени ожидания и крайнего срока следующим шагом будет создание тела сообщения-запроса.

В этом сценарии запрос представляет собой сообщение OptimizeToursRequest закодированное как JSON в REST API.

Чтобы составить сообщение-запрос, выполните следующие шаги:

1. Начнем с базовой структуры запроса , которая выглядит следующим образом:

   {
     "timeout": ...,
     "model": {
       "shipments": [...],
       "vehicles": [...],
       "globalStartTime": "...",
       "globalEndTime": "..."
     }
   }
   

   Более подробную информацию о структуре см. в руководстве по основным понятиям базовой структуры (ShipmentModel, Shipment и Vehicle) .

2. Определите отправку. В поле shipments » добавьте сообщение Shipment для каждой собаки, которую нужно забрать и отвезти утром. Здесь вы указываете предпочтительное для владельца собаки место и время, а также местоположение и время детского сада, куда нужно отвезти собак.

   1. Для каждой собаки создайте запрос VisitRequest для забора и еще один для доставки, который в этом сценарии называется отправкой в ​​дневной присмотр.

      • В настройках забора собак установите в качестве точки arrivalWaypoint место забора собаки (башня Койт для бернской зенненхунда или парк South Sunset Playground для чихуахуа), а в качестве timeWindows — желаемое владельцем время забора (с 7:30 до 9:30).

      • При доставке установите в arrivalWaypoint детский сад, а в timeWindows — требуемое время высадки (с 9:30 до 11:30).

      Более подробную информацию о временных окнах см. в разделе Временные окна .

   2. Вы можете использовать поле label , чтобы добавить идентификатор для каждой партии товара, например, «Бернский зенненхунд» или «Чихуахуа». Это поможет вам идентифицировать грузы в ответе.

   Более подробную информацию об определении поставок см. в разделе Отправка .

3. Определите транспортные средства. В поле vehicles добавьте сообщение Vehicle для вашего фургона, указав детский сад в качестве начальной и конечной точки маршрута, стоимость оплаты труда водителя и часы работы фургона.

   1. Установите начальную и endWaypoint startWaypoint для фургона в соответствии с начальными и конечными точками маршрута дня, то есть в детском саду возле парка Mission Dolores.

   2. Чтобы минимизировать операционные расходы, необходимо определить ограничения по затратам для вашего бизнеса. Установите параметр затрат costPerHour равным 27, что соответствует сумме, которую вы платите водителю за управление фургоном для собак. Подробнее о параметрах затрат см. в разделе «Модель затрат» .

      Важно: затраты необходимы оптимизатору для поиска оптимального маршрута. Без них оптимизатор рассматривает все решения как равные.

   3. Чтобы оптимизатор мог построить маршрут в соответствии с рабочими часами микроавтобуса, задайте для параметра startTimeWindows допустимый диапазон времени начала движения микроавтобуса и для endTimeWindows допустимый диапазон времени возвращения водителя в детский сад. Подробнее о временных окнах см. в разделе Временные окна .

4. Установите глобальное временное окно. Глобальное временное окно представляет собой временной интервал, в течение которого фургон может забирать и отвозить животных из вашего детского сада в течение дня. Для этого сценария установите globalStartTime на 7:00 утра и globalEndTime на 19:00 вечера для 13 февраля 2024 года, что соответствует часам работы вашего детского сада для собак.

3. Отправить запрос

Ниже приведен простой curl запрос, основанный на сценарии дневного ухода за собаками, в котором используется блокирующий метод optimizeTours .

Перед отправкой запроса замените PROJECT_NUMBER_OR_ID в примере кода на идентификатор вашего проекта Google Cloud.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": 2s,
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
EOM

Параметры запроса, используемые в запросе

В следующей таблице описаны параметры запроса, используемые в тексте примера сценария. Вы можете фильтровать содержимое по родительскому элементу или по текстовому поиску.

OptimizeToursRequest ShipmentModel Отгрузка VisitRequest Транспортное средство

Родитель	Параметр	Тип недвижимости	Описание
OptimizeToursRequest	model	объект ( ShipmentModel )	Это ядро ​​вашего запроса. Это единый объект, в котором вы описываете всю свою проблему, включая всех собак, которых нужно забрать и отвезти ( shipments ), и фургон в вашем автопарке ( vehicles ). Представьте себе, что это полный план решения проблемы, которую нужно оптимизировать.
	timeout	Продолжительность	Этот параметр определяет максимальное время, в течение которого сервер обрабатывает запрос, прежде чем вернуть ответ. Используйте этот параметр, чтобы сократить время ожидания. Для небольших и быстрых запросов, например, для этого сценария ухода за собаками, установите значение 2 с.
ShipmentModel	shipments[]	массив объектов ( Shipment )	Это массив объектов, где каждый объект представляет собой собаку, которую нужно поднять или отвести.
	vehicles[]	массив объектов ( Vehicle )	Это массив объектов, каждый из которых определяет транспортное средство в вашем автопарке. Здесь вы описываете свои ресурсы, например, фургон, который осуществляет погрузку и высадку пассажиров. Для оптимизации маршрута необходимо указать хотя бы одно транспортное средство.
	globalStartTime	Метка времени	Это самое раннее возможное время наступления любого события во всей вашей модели. Этот параметр сужает задачу оптимизации по времени, что критически важно для точного расчета дорожного движения и маршрутизации. Для этого сценария с собачьим детским садом установите это значение на самое раннее время, когда водитель может управлять фургоном в течение дня, то есть на 7:00 утра 13 февраля 2024 года.
	globalEndTime	Метка времени	Это самое позднее возможное время для любого события во всей вашей модели. Для этого сценария с собачьим детским садом установите это время на ожидаемое время окончания работы фургона, то есть на 19:00 13 февраля 2024 года.
Shipment	pickups[]	массив объектов ( VisitRequest )	Это список всех возможных вариантов забора груза. Оптимизатор выбирает наиболее подходящий для решения вашей проблемы. Для этого сценария с собачьим детским садом перечислите места забора и временные интервалы, указанные каждым владельцем для каждой собаки.
	deliveries[]	массив объектов ( VisitRequest )	Это список всех возможных вариантов доставки груза. Оптимизатор выбирает наилучший вариант для решения вашей проблемы. Для этого сценария с собачьим детским садом укажите местоположение собачьего детсада и временной интервал, когда водителю необходимо вернуться, чтобы пообедать для каждой собаки.
	label	нить	Это идентификатор конкретной партии груза в вашем запросе. Вы можете указать метки в запросе, чтобы упростить чтение ответа. Для этого сценария ухода за собаками используйте описательную строку, например «Чихуахуа», «Бернский зенненхунд» или кличку собаки, чтобы сопоставить решение с вашими данными при получении ответа API.
VisitRequest	arrivalWaypoint[]	объект ( Waypoint )	Это место конкретного посещения на маршруте. Вы можете указать его, используя координаты широты и долготы, идентификатор места или направление. В этом сценарии ухода за собаками укажите место, указанное владельцем для pickups , и адрес детского сада для deliveries .
	timeWindows[]	массив объектов ( TimeWindow )	Это массив объектов, определяющих временные ограничения для забора или доставки собак. В данном сценарии используйте его для определения временного интервала для забора каждой собаки и приемлемого временного интервала для приведения собак в детский сад.
Vehicle	startWaypoint[]	объект ( Waypoint )	Это начальная точка маршрута транспортного средства, определяемая координатами широты и долготы или идентификатором места. Этот параметр указывает оптимизатору, где транспортное средство должно начать маршрут. Если эта точка не указана, оптимизатор выберет в качестве начальной точки один из пунктов забора или доставки. Для этого сценария с собачьим детским садом, поскольку водитель начинает день в детском саду, используйте координаты парка Мишн Долорес.
	endWaypoint[]	объект ( Waypoint )	Это конечный пункт назначения маршрута транспортного средства, определяемый координатами широты и долготы или идентификатором места. Этот параметр указывает оптимизатору, где транспортное средство должно завершить маршрут. Если эта точка не указана, оптимизатор выберет один из пунктов забора или доставки в качестве конечной точки маршрута. В данном сценарии с собачьим детским садом, поскольку водитель должен завершить день в детском саду, используйте координаты парка Мишн Долорес.
	costPerHour	число	Это стоимость каждого часа использования транспортного средства, независимо от того, находится ли оно в движении или стоит. Для этого сценария ухода за собаками используйте эту стоимость для расчета почасовой оплаты труда водителя.
	startTimeWindows[]	массив объектов ( TimeWindow )	Это приемлемое время для водителя, чтобы начать движение на фургоне для утреннего вывоза собак.
	endTimeWindows[]	массив объектов ( TimeWindow )	Это приемлемое время для водителя, чтобы закончить движение на фургоне и припарковаться у центра дневного пребывания собак.

Следующий

Интерпретировать ответ