Перейти к содержанию
9 минут чтения
Тема: Практика PHP · Геолокация · Филиалы

Как получить геолокацию пользователя и показать ближайший филиал

Для примера поможем клиенту сервисного центра выбрать филиал. Бот предложит отправить геолокацию или выбрать адрес вручную, сравнит точку с действующими филиалами и покажет ближайший. Координаты понадобятся для одного поиска, а в заявке останется выбранный филиал.

Готовим список филиалов и шаг диалога

Нужны обычный Telegram-бот, обработчик входящих обновлений и список филиалов. PHP-пример рассчитан на PHP 8.3+ на 64-битной системе. HTTP-приёмник и клиент Telegram уже должны быть подключены; ниже показаны параметры методов и отдельная функция поиска, которую можно вызвать из вашего обработчика.

Для каждого филиала храните стабильный id, название, адрес, latitude, longitude и признак активности. Координаты принадлежат входу для посетителей, а не приблизительному центру улицы. Если разные отделения оказывают разные услуги, сначала отфильтруйте список по выбранной услуге, затем ищите ближайшее.

После команды /branches сохраните состояние awaiting_location для сочетания bot_id, chat_id и user_id. Ограничьте его срок, например десятью минутами. Если пользователь уже перешёл к другой задаче, случайная геолокация не должна менять филиал в старой заявке. Основы такого состояния описаны в статье о пошаговой анкете.

Запрашиваем координаты кнопкой

request_location относится к обычной reply-клавиатуре и доступен в личном чате. Это не inline-кнопка с callback_data. Отправьте sendMessage с пояснением, для чего нужна точка, и оставьте рядом обычную текстовую кнопку для ручного выбора.

JSON · параметры sendMessage
{
  "chat_id": 123456789,
  "text": "Найду ближайший сервисный центр. Отправьте геолокацию или выберите адрес вручную.",
  "reply_markup": {
    "keyboard": [[{"text": "Отправить геолокацию", "request_location": true}], [{"text": "Выбрать адрес вручную"}]],
    "resize_keyboard": true,
    "one_time_keyboard": true
  }
}

Число chat_id здесь демонстрационное: используйте ID личного чата из проверенного update. Если диалог начат в группе, предложите продолжить в личном чате с ботом. Не пытайтесь получить координаты участников группы через эту кнопку.

После отправки точки бот получает message.location с latitude и longitude. Отдельного callback_query здесь нет. Если человек закрыл запрос или отказал клиенту Telegram в доступе, бот не получает специальное событие «отказ»: оставьте ручной путь доступным без ожидания таймера.

one_time_keyboard скрывает клавиатуру после использования, но не отменяет состояние на сервере. Когда выбор завершён или отменён, отправьте сообщение с reply_markup={"remove_keyboard":true} и завершите awaiting_location. Поведение кнопки описано в KeyboardButton.

Принимаем точку только в подходящем контексте

Проверьте подлинность webhook, тип личного чата, отправителя и актуальный шаг. Координаты должны быть числами: широта от −90 до 90, долгота от −180 до 180. Ноль — допустимое значение, поэтому empty() для проверки координат не подходит.

Telegram также позволяет прислать произвольную точку карты. По одному message.location нельзя доказать физическое присутствие человека в этой точке или определить, нажал ли он именно вашу кнопку. Используйте её как место поиска, а не как подтверждение адреса проживания или права на услугу.

В этом сценарии обрабатываем обычный message один раз. Обновления live location в edited_message не запускают постоянный пересчёт. Если нужен поиск при движении, проектируйте отдельный режим с явным завершением и сроком действия.

При некорректном значении предложите повторить отправку или открыть список адресов. Если передана неточная точка, результат тоже будет приблизительным. Для соседних филиалов можно показать два варианта и дать пользователю выбрать удобный.

Ищем ближайшую точку на PHP

Для небольшой сети достаточно сравнить расстояния по сфере. Функция ниже использует формулу гаверсинусов и возвращает филиал с distance_km либо null для пустого списка. Передайте в неё только актуальные и подходящие по услуге филиалы из вашей БД.

PHP · nearest-branch.php
<?php
declare(strict_types=1);

function validCoordinates(float $lat, float $lon): bool
{
    return is_finite($lat) && is_finite($lon)
        && $lat >= -90 && $lat <= 90 && $lon >= -180 && $lon <= 180;
}

/** @param list<array{id: int, title: string, address: string, latitude: float, longitude: float}> $branches
 * @return array<string, mixed>|null
 */
function nearestBranch(float $lat, float $lon, array $branches): ?array
{
    if (!validCoordinates($lat, $lon)) {
        throw new InvalidArgumentException('Некорректные координаты');
    }
    $best = null;
    foreach ($branches as $branch) {
        $bLat = $branch['latitude'];
        $bLon = $branch['longitude'];
        if (!validCoordinates($bLat, $bLon)) {
            throw new InvalidArgumentException('Проверьте координаты филиала');
        }
        $dLat = deg2rad($bLat - $lat);
        $dLon = deg2rad($bLon - $lon);
        $a = sin($dLat / 2) ** 2
            + cos(deg2rad($lat)) * cos(deg2rad($bLat)) * sin($dLon / 2) ** 2;
        $distance = 6371.0088 * 2 * asin(sqrt(max(0.0, min(1.0, $a))));
        if ($best === null || $distance < $best['distance_km']
            || ($distance === $best['distance_km'] && $branch['id'] < $best['id'])) {
            $best = $branch + ['distance_km' => $distance];
        }
    }
    return $best;
}

При чтении DECIMAL из PDO преобразуйте координаты филиалов в float. Результат — расстояние по прямой по поверхности сферы. Он не учитывает реку, заборы, дороги, пробки и вход с другой стороны здания. Не называйте это временем в пути или длиной автомобильного маршрута.

Если ближайшая точка находится слишком далеко, например дальше принятого вами радиуса обслуживания, сообщите об этом и предложите список городов. Порог — правило бизнеса, а не ограничение Telegram. Для расчёта маршрута понадобится отдельный картографический сервис; ключи такого сервиса не передаются пользователю.

Показываем адрес и даём ручной выбор

Сначала отправьте название, полный адрес и фразу «Примерно 2,4 км по прямой». В sendVenue передайте координаты филиала, title и address. Это координаты места назначения, а не повторная публикация точки клиента.

JSON · параметры sendVenue с демонстрационным адресом
{
  "chat_id": 123456789,
  "latitude": 55.75,
  "longitude": 37.61,
  "title": "Сервисный центр — пример",
  "address": "Демонстрационный адрес, замените реальным"
}

Добавьте выбор «Этот филиал» и «Другие адреса» через inline-кнопки. Callback передаёт только стабильный ID филиала. Перед записью в заявку ещё раз проверьте активность и доступность услуги; старая клавиатура не должна позволять выбрать закрытое отделение.

При ручном выборе сначала покажите города, затем адреса действующих филиалов. Для длинного списка пригодится постраничный каталог. Этот путь работает и при отказе от геолокации, и когда клиент ищет филиал рядом с будущим местом поездки.

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

Проверяем результат и хранение данных

  • Пользователь отправляет точку непосредственно у филиала: выбирается именно он, расстояние близко к нулю.

  • Отказ от доступа не блокирует сценарий: можно выбрать город и адрес вручную.

  • Пустой список и отсутствие филиала в радиусе дают понятный ответ.

  • Нулевые координаты принимаются, широта 91 и нечисловые значения отклоняются.

  • Повтор update не создаёт повторного выбора; после отмены старые координаты не меняют заявку.

Для этого сценария достаточно сохранить branch_id и способ выбора location/manual. Если координаты после расчёта не нужны, не переносите их в заявку и обычные логи. Учтите также хранение исходных webhook и резервных копий: удаление одного поля не удаляет все копии события.

При работе через BotGate поиск выполняет ваше приложение. request_location, sendMessage и sendVenue передаются как параметры Telegram API; для входящих событий используйте проверку подписи из документации webhook. Структуры результата описаны в Location и sendVenue.