--- name: 2gis description: >- Геоданные 2ГИС: поиск мест и организаций, геокодирование адресов и обратное геокодирование координат, построение маршрутов (авто, пешком, вело, самокат, мото, грузовик, такси), расчёт изохрон (зоны достижимости), создание статической карты PNG с маркерами, линиями и полигонами и кликабельные ссылки на интерактивную карту 2ГИС. Требует API-ключ 2ГИС. version: 1.1.0 type: extension runtime: python3 entry: plugin.py plugin_api: "1.3" timeout_sec: 60 permissions: - net - tool - route - widget env_from_settings: [] tools: - name: check description: "Проверка подключения к API 2ГИС: какие ключи заданы и жив ли сервис." - name: geocode description: "Адрес → координаты (прямое геокодирование)." - name: reverse_geocode description: "Координаты → ближайший адрес (обратное геокодирование)." - name: search_poi description: "Поиск мест и организаций по запросу рядом с точкой." - name: route description: "Маршрут между точками: расстояние, время, маневры, альтернативы." - name: isochrone description: "Изохроны: зона, достижимая от точки за заданное время (WKT)." - name: map description: "Статическая карта PNG с маркерами, линиями и полигонами." trigger: >- Пользователь спрашивает про места, организации, адреса и координаты, просит найти что-то рядом («аптека рядом», «кофейни поблизости»), построить маршрут, посчитать время/расстояние в пути, показать зону достижимости (за 15 минут пешком), нарисовать карту с отметками или дать ссылку на карту 2ГИС, чтобы открыть её в деталях — по России и СНГ, где работает 2ГИС. when_to_use: >- Геозадачи через 2ГИС: поиск организаций и мест, адрес↔координаты, маршруты, изохроны, статические карты. НЕ для: поиска готовых изображений в интернете, GPS-трекинга, бронирования, отзывов о местах (2ГИС не отдаёт отзывы через эти API). Для поиска по миру вне зоны покрытия 2ГИС используй другие инструменты. --- # 2ГИС — геоданные для агента Extension-навык поверх официальных API 2ГИС. Повторяет набор инструментов официального MCP-сервера 2ГИС (`github.com/2gis/2gis-mcp`), но работает как нативный extension Ouroboros — без Node.js, без `npm install`, без сборки. Источники: - документация MCP-сервера: https://docs.2gis.com/api/ai/mcp-server - код-референс: https://github.com/2gis/2gis-mcp ## Setup Навык использует **два API-ключа** 2ГИС (как рекомендует сама 2ГИС — так раздельно контролируется расход карт/поиска и навигации): | Поле в настройках | Что покрывает | |---|---| | **Ключ: карты и поиск** | Static API, Geocoder API, Places/Catalog API | | **Ключ: навигация** | Routing API, Isochrone API | Если у вас один ключ на все сервисы — вставьте его в оба поля. Ключи берутся из **«Настройки» → «Расширенные» → «2ГИС»**. Если поле пустое, навык попробует переменные окружения `TWOGIS_MAP_API_KEY` / `TWOGIS_ROUTING_API_KEY`. Где взять ключ: зарегистрируйтесь в [Менеджере Платформы 2ГИС](https://platform.2gis.ru/) и оформите бесплатный **демо-ключ** (действует 30 дней, все нужные API подключены автоматически) или платную подписку. Ключи хранятся только в приватном состоянии навыка и в чат не попадают. ## Инструменты ### `check` Префлайт: какие ключи заданы, доступны ли Catalog и Routing API. Дёшево, без побочных эффектов. Зови перед первой задачей или при непонятной ошибке. ### `geocode(query)` Адрес → координаты. Поддерживает российские адреса и названия организаций. Возвращает адрес, координаты и уверенность (confidence). ### `reverse_geocode(lat, lon, radius?)` Координаты → ближайший адрес. `radius` — радиус поиска в метрах (0–2000). ### `search_poi(query, lat, lon, radius, page?)` Поиск мест и организаций рядом с точкой. `radius` — в метрах (например 500). Возвращает имя, адрес, координаты, рубрики и расстояние от центра. ### `route(start, end, profile, via?, route_mode?, traffic_mode?, filters?)` Маршрут между точками. - `start` / `end` — либо `{"lat": 55.75, "lng": 37.62}`, либо строка-адрес (будет геокодирована), либо `"55.75,37.62"`. - `profile` — `car` · `taxi` · `pedestrian` · `bicycle` · `scooter` · `motorcycle` · `truck`. - `via` — промежуточные точки. - `route_mode` — `fastest` (по умолчанию) или `shortest`. - `traffic_mode` — `jam` (пробки в реальном времени, по умолчанию) или `statistics`. - `filters` — что исключить: `toll_road`, `ferry`, `dirt_road`, `highway`, `ban_car_road`, `ban_stairway`. Возвращает расстояние, время в пути, маневры и альтернативные маршруты. ### `isochrone(lat, lon, profile, intervals, reverse?, start_time?)` Зона достижимости от точки за заданное время (изохрона) в формате WKT. - `profile` — `car` · `pedestrian` · `bicycle` · `public_transport`. - `intervals` — секунды, максимум 5 значений, каждое ≤ 3600. - `reverse` — `false` = зона, достижимая ОТ точки; `true` = зона, из которой можно ДОЕХАТЬ до точки. - Для `public_transport` `reverse` не поддерживается. ### `map(...)` Статическая карта PNG. **Ключ не требуется.** - `lat`, `lon` — центр карты. - `zoom` — 1–18 (по умолчанию 14). - `markers` — `[{"lat":…, "lon":…, "color":"red"}]`. Цвета: `blue`, `red`, `green`, `orange`, `yellow`, `purple`, `pink`, `grey`, `black`. - `lines` — `[{"points":[{"lat":…,"lon":…}, …], "color":"ff0000", "width":5}]`. Цвет линий — hex `RRGGBB`. - `polygons` — `[{"points":[…], "strokeColor":"ff0000", "fillColor":"ff000080"}]`. - `width` / `height` — размер в пикселях (120–1280 / 90–1280). Карта показывается в чате автоматически, и рядом ставится **кликабельная ссылка** на интерактивную карту 2ГИС (поле `map_url`). Отдельно отправлять карту не нужно. ## Ссылки на интерактивную карту Статический PNG — это снимок; у него самого ссылки нет. Поэтому инструменты дополнительно возвращают веб-ссылки (и ставят их кнопкой в чат): - `map` → `map_url` — карта `https://2gis.ru/?m=,/`. - `geocode` → `map_url` — найденная точка на карте (zoom 16). - `search_poi` → `map_url` — центр поиска на карте. - `route` → `route_url` — маршрут `https://2gis.ru/directions/points/,|,|<…>` (старт → промежуточные точки `via` → финиш). Формат ссылок проверен живыми запросами; долгота идёт первой, точки соединяются `|`. ## Примеры ``` # аптеки в радиусе 800 м от центра search_poi(query="аптека", lat=55.7558, lon=37.6173, radius=800) # маршрут на машине от адреса до адреса route(start="Красная площадь, Москва", end="Шереметьево", profile="car") # что достижимо за 15 минут пешком isochrone(lat=55.7558, lon=37.6173, profile="pedestrian", intervals=[900]) # карта с маркером (+ ссылка на интерактивную карту) map(lat=55.7558, lon=37.6173, zoom=16, markers=[{"lat":55.7558,"lon":37.6173,"color":"red"}]) ``` ## Ограничения - 2ГИС покрывает Россию и СНГ, а лучше всего — крупные города. Адрес вне зоны покрытия вернёт пустой результат, это не ошибка навыка. - Тарифы и лимиты те же, что при прямых запросах к API 2ГИС: демо-ключ ограничен по числу запросов. - Навык только читает геоданные: он ничего не бронирует и не меняет. - Требуется сетевой доступ (`permissions: net`). ## Вопросы и быстрый чеклист - **«Ключ не задан»** — открой «Настройки» → «Расширенные» → «2ГИС» и вставь ключ. `check` покажет, какой именно ключ отсутствует. - **Адрес не найден** — попробуй добавить город/регион или передай координаты напрямую (их можно взять из `geocode`). - **Маршрут не строится** — проверь, что задан ключ навигации (Routing API). - **Карта пустая** — вероятно, неверный `zoom` или центр вне покрытия.