API-пайплайн: поиск проектов по месту и на карте

Индекс: API-пайплайны — индекс

Цель: найти проекты (и другие карточки) в городе или стране и показать их на карте.

Для публичных карточек токен не нужен.

Шаги

1. Найдите место.

GET /v0/search/geo/cities?q=tashkent&limit=10
→ {"hits": [{"geonameid": 1512569, "name": "Tashkent", "country_iso": "UZ", "country_name": "Uzbekistan",
             "lat": 41.26465, "lon": 69.21627, "label": "Tashkent, UZ"}]}

GET /v0/search/geo/countries?q=uzbek
→ {"hits": [{"iso": "UZ", "name": "Uzbekistan"}]}

country=UZ ограничивает города одной страной. Одно место по id: GET /v0/geo/cities/{geonameid}, GET /v0/geo/countries/{iso}.

2. Превратите его в карточку места. Фильтры принимают nonce мест, а не geonameid или коды ISO.

GET /v0/graph/resolve/@rub.geo-1512569   → {"card_type": "rubric", "nonce": "<city place>", "kind": "place", …}
GET /v0/graph/resolve/@rub.geo-uz        → {"card_type": "rubric", "nonce": "<country place>", "kind": "place", …}

Город — это @rub.geo-<geonameid>, страна — @rub.geo-<iso, lowercase>.

3. Ищите в нём.

POST /v0/search/graph
{"query": "", "card_type": "project", "filters": {"locations": ["<country place>"]}, "limit": 50}
→ {"hits": [{"title": "…", "location": {"nonce": "…", "title": "Tashkent", "geo": {"lat": 41.27, "lon": 69.25}}, …}], …}

• locations оставляет только карточки в этом месте или где-либо внутри него (страна включает свои регионы и города).
• Чтобы сортировать по расстоянию, ничего не скрывая, отправьте вместо этого preference_city {"nonce", "lat", "lon"} и radius_km.
• Другие фильтры: API-пайплайн: поиск по графу. Группы Telegram по месту: API-пайплайн: добавить свои Telegram-группы, найти группы по ключевому слову, месту или рубрике, проверить их и подключить к кампании.

4. Покажите на карте. location.geo (lat, lon) каждого результата — это метка; у результатов без location метки нет. Страница отдельной карточки содержит тот же location.

5. Просмотр места: GET /v0/graph/rubrics/{place nonce}?contained_limit=50 → карточка места с geo и contained (места внутри него).

Что происходит за кадром

• Проект привязан к одному месту; это может быть город или регион. Фильтр по городу пропускает проекты, привязанные к окружающему региону: фильтруйте по стране или сортируйте через preference_city.

Правила

• GET /v0/geo/cities/{geonameid}: 400 geonameid must be an integer; неизвестный id или ISO: 404.
• Поиск мест отвечает пустым списком hits, если ничего не найдено; неверный country не даёт результатов.

Поверхность API