API pipeline: Find projects by place and on the map

Index: API pipelines — index

Goal: find projects (and other cards) in a city or country and place them on a map.

No token needed for public cards.

Steps

1. Find the place.

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 narrows cities to one country. One place by id: GET /v0/geo/cities/{geonameid}, GET /v0/geo/countries/{iso}.

2. Turn it into a place card. Filters take place nonces, not geonameids or ISO codes.

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", …}

A city is @rub.geo-<geonameid>, a country @rub.geo-<iso, lowercase>.

3. Search in it.

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 keeps only cards in that place or anywhere inside it (a country holds its regions and cities).
• To rank by distance without hiding anything, send preference_city {"nonce", "lat", "lon"} and radius_km instead.
• More filters: API pipeline: Search the graph. Telegram groups by place: API pipeline: Submit your Telegram groups, find groups by keyword, place or rubric, vet them and attach them to a campaign.

4. Map it. Each hit's location.geo (lat, lon) is the pin; hits without location have no pin. A single card's page carries the same location.

5. Browse a place: GET /v0/graph/rubrics/{place nonce}?contained_limit=50 → the place card with geo and contained (the places inside it).

Behind

• A project is pinned to one place; it may be a city or a region. A city filter misses projects pinned to the surrounding region: filter by the country, or rank with preference_city.

Rules

• GET /v0/geo/cities/{geonameid}: 400 geonameid must be an integer; unknown id or ISO: 404.
• Place search answers an empty hits list when nothing matches; an invalid country gives no hits.

API surface