Для поиска остановок вокруг точки передайте её широту, долготу и радиус в API близости. Проверьте статус ответа, возвращённые объекты и информацию о покрытии перед отображением списка или карты.
В контракте ROOTE roote-1.0.0 маршрут GET /v1/transit/nearby находит транспортные точки поблизости. Он не получает отправления или оповещения в реальном времени. Поиск точки и поиск её следующего прохода — это разные операции.
Установка параметров
Запрос использует lat для широты и lng для долготы. Псевдоним lon также описан в контракте. Параметр radius задаёт радиус в метрах; limit ограничивает количество результатов. Фильтр modes может указывать виды транспорта.
| Параметр | Пример | Назначение |
|---|---|---|
| lat | 44.8378 | Широта поисковой точки |
| lng | -0.5792 | Долгота поисковой точки |
| radius | 600 | Запрашиваемый радиус в метрах |
| limit | 10 | Запрашиваемый лимит результатов |
| modes | bus,tram | Искомые виды транспорта |
Эти координаты служат примером поиска в Бордо; они не гарантируют остановку. Смотрите контракт OpenAPI ROOTE для актуальных ограничений, полей и условий.
Найдите остановки вокруг вас.
Исследуйте остановки в городе или возле вашего местоположения. Просмотрите детали, чтобы узнать виды транспорта и доступную информацию.
Отправьте первый запрос на сервере
Пример JavaScript для Node.js с поддержкой fetch. Токен, если нужен, хранится в переменной окружения на сервере. Пример не требует секретов в браузере.
async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
const url = new URL('https://api.roote.ai/v1/transit/nearby');
url.search = new URLSearchParams({
lat: '44.8378',
lng: '-0.5792',
radius: '600',
limit: '10',
modes: 'bus,tram'
}).toString();
const headers = { Accept: 'application/json' };
if (token) headers.Authorization = `Bearer ${token}`;
const response = await fetch(url, {
headers,
signal: AbortSignal.timeout(10000)
});
if (!response.ok) {
throw new Error(`Erreur HTTP ${response.status}`);
}
const data = await response.json();
if (data.contract_version !== 'roote-1.0.0') {
throw new Error('Version du contrat non reconnue');
}
if (!['success', 'empty', 'partial'].includes(data.status)) {
throw new Error('Recherche indisponible');
}
if (!Array.isArray(data.stations)) {
throw new Error('Réponse sans collection stations valide');
}
return {
status: data.status,
stations: data.stations,
lines: data.lines,
operators: data.operators,
coverage: data.coverage,
warnings: data.warnings,
attributions: data.attributions,
meta: data.meta
};
}
Контракт предусматривает анонимный или по токену доступ, в зависимости от правил. Проверьте свои права и лимиты. Корректный HTTP ответ не гарантирует правильность данных; в продакшене валидируйте объекты по схеме.
Чтение сущностей и их отношений
Коллекция stations содержит найденные места. Для каждого смотрите id, name, entity_kind, location и distance_meters. Ссылки line_ids и operator_ids соответствуют коллекциям lines и operators, если они есть.
Отображайте географическое расстояние как таковое. Не превращайте его в время ходьбы без маршрута. Руководство найти ближайшую остановку объясняет, почему доступы могут влиять на реальный путь.
Обрабатывайте неизвестные явно. В контракте accessibility.wheelchair может иметь значение unknown: это не «да» и не «нет». Объявленная ёмкость отправлений не равна списку отправлений.
Отобразить список или карту
Используйте идентификатор для стабильности интерфейса, имя для подписи, location для позиции. Связывайте линии по ссылкам, а не по именам.
Если показываете цвета линий или подписи из данных, считайте их внешним вводом и валидируйте. Для имён используйте текст, а не вставляйте HTML.
Сохраняйте атрибуцию источников и показывайте те, что обязательны по контракту.
Обработать пустой результат, частичный ответ и ошибку
Результат empty — поиск без найденных объектов в зоне. Это не значит отсутствие транспорта. Ответ partial может содержать полезные места и предупреждать о лимитах: показывайте результат и предупреждение.
Читайте coverage, warnings и ограничения в meta. Усечённый список не гарантирует полного покрытия. При сетевых или HTTP ошибках показывайте недоступность, не заменяя результат на «нет остановок».
Для кода 429 смотрите инструкции по повтору и возможные заголовки сервиса. Избегайте циклических повторов.
Различать станции, зоны и платформы
Поле entity_kind разделяет уровни мест. Два близких результата могут быть разными платформами; похожие имена — разными источниками.
Не сливайте места только по близости. Используйте отношения и идентичности из сервиса. Наше руководство GTFS, GTFS-RT и GBFS объясняет контекст данных.
Подготовка к продакшен интеграции
Запускайте поиск при полезных изменениях позиции или фильтров. Объединяйте одинаковые вызовы, задавайте таймауты и адаптируйте кэш под вид данных и условия сервиса.
Список мест и данные в реальном времени имеют разные требования к свежести. Тестируйте все варианты ответов (полные, пустые, частичные, с ошибками) перед показом пользователям.
Расширение поиска на городские службы
Остановки и городские службы используют разные маршруты. Чтобы искать туалеты в районе той же точки, GET-запрос /v1/services/nearby ожидает lat и lon с параметром types=toilets. Не передавайте modes=toilets в этот маршрут: этот термин относится к URL карты, а не к фильтру службы.
Следующий пример на JavaScript формирует URL для Services с радиусом 600 метров. Он не запускает запрос; повторно используйте уже описанные средства HTTP и контракт. Ожидаемая коллекция — services вместо stations. Сохраняйте service_type, location, distance_meters и реально присутствующие атрибуты.
REST-контракт документирует, в частности, toilets, drinking_water, fountain, wifi, parking, charging, aed и locker. Типы, предоставляемые MCP, могут отличаться. Чтобы узнать допустимые параметры, их границы и ограничения вашего доступа, обратитесь к схеме используемого интерфейса.
Атрибуты службы не гарантируют её открытость в момент поиска. Неизвестная доступность не равна недоступности; пустой список из-за ошибки не доказывает отсутствия туалетов. Храните данные отдельно по каждой категории, а не сводите всё к имени и точке.
Для объединённой карты сопоставьте результаты с их категориями и идентификаторами. Показывайте ошибку Services, не удаляя остановки, полученные от Transit. Поиск остаётся по той же точке, но статусы и покрытие могут различаться.
const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
lat: '44.8416106', lon: '-0.5810938',
radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());Диагностика пустого или ошибочного поиска
Встраивание отфильтрованной карты прямо на сайт
Создание помощника на основе этих поисков
Часто задаваемые вопросы
Показывает ли Nearby следующие отправления?
Нет, в этом контракте. Этот маршрут лишь ищет транспортные места; отправления требуют отдельного функционала.
Можно ли показывать пустой список после ошибки?
Показывайте недоступность. Ошибка не доказывает отсутствие остановок.
Можно ли хранить API токен в браузере?
Секрет должен храниться на сервере. Используйте предусмотренную модель доступа для вашего приложения и аккаунта.