2gis · v1.1.1 · 2026-10-08 · sha256 6465339a3d6428bf
2gis v1.1.1A
Immutable. This exact content never changes and is served at /api/v1/blob/6465339a3d6428bf.
---
name: 2gis
description: >-
Геоданные 2ГИС: поиск мест и организаций, геокодирование адресов и обратное
геокодирование координат, построение маршрутов (авто, пешком, вело, самокат,
мото, грузовик, такси), расчёт изохрон (зоны достижимости), создание
статической карты PNG с маркерами, линиями и полигонами и кликабельные ссылки
на интерактивную карту 2ГИС. Требует API-ключ 2ГИС.
version: 1.1.1
type: extension
runtime: python3
entry: plugin.py
plugin_api: "2.0"
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=<lon>,<lat>/<zoom>`.
- `geocode` → `map_url` — найденная точка на карте (zoom 16).
- `search_poi` → `map_url` — центр поиска на карте.
- `route` → `route_url` — маршрут
`https://2gis.ru/directions/points/<lon>,<lat>|<lon>,<lat>|<…>`
(старт → промежуточные точки `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` или центр вне покрытия.