# Народный рейтинг городов мира — данные для агентов

> relocat.io/rating — оценки городов для переезда от людей, которые там жили.
> 44 критерия (зима, море, цены, школы, безопасность, путь к ПМЖ…), шкала 1–5, у каждой ячейки —
> средняя и число оценок. Плюс рейтинги людей `relocat.io/t/<адрес>` — их веса и свои оценки.
> JSON читается без входа. Таблицы (`export.csv`, `export.xlsx`) — по бесплатному ключу: человек регистрируется на
> relocat.io и выдаёт ключ в профиле («Вход и доступ» → «Ключи для ИИ-агентов»), право «читать» есть у каждого ключа.
> Передавайте ключ во всех запросах — `Authorization: Bearer <ключ>` или `?key=<ключ>`: так чтение учитывается.
> Без ключа выгрузка отвечает 401 — попросите человека выдать ключ.

English: [agent.en.md](https://relocat.io/rating/agent.en.md).

Готовый скилл (русский и английский): [SKILL.md](https://relocat.io/rating/SKILL.md) —
положите в `~/.claude/skills/relocat-world/SKILL.md` или поставьте из GitHub:
https://github.com/relocat-io/relocat-skills — там же обновления.

## Что за данные

- **Город × критерий.** Оценка 1–5 от человека с опытом: живёт сейчас, жил раньше, бывал подолгу или
  туристом. Средняя — взвешенная (живущий и проживший больше года весит 1, меньше года — 0,7, бывал подолгу — 0,5,
  турист — 0,3), при 10
  и больше оценках отбрасываются по 10 % крайних. Ячейка показывается от 3 оценок.
- **Балл города** 0–100 при заданных весах: `Σ w·(v−1)/4 / Σ w × 100` по критериям с весом > 0 и
  известной оценкой. Критерий «без этого никак» (`must`): оценка ниже 3 — город уходит в конец.
- **Рейтинги людей** — набор городов, веса 0–10, свои критерии и свои оценки поверх общих средних.
- Обновляется сразу после новой оценки; кэш таблицы — до 5 минут.

## Эндпоинты

База — `https://api.relocat.io/api/v1`. Ответы — JSON, UTF-8.

| Запрос | Что вернёт |
|---|---|
| `GET /world/criteria` | критерии: `key, name, group, description, hi, lo` (подсказки к 5 и 1) |
| `GET /world/cities[?q=]` | города рейтинга: `slug, name, country, country_code, region, status` |
| `GET /world/table[?who=all\|residents]` | вся таблица: `cities[].scores[key] = { avg, n, country? }`, `raters`; `country: true` — своих оценок по страновому критерию мало, среднее по городам страны |
| `GET /world/cities/{slug}/feed[?criterion=]` | комментарии к оценкам и распределение `dist` 1–5 |
| `GET /world/lists[?sort=views\|likes\|discussed\|new]` | галерея рейтингов людей: по просмотрам (по умолчанию), лайкам, живому обсуждению, новизне |
| `GET /world/lists/{адрес}` | рейтинг человека целиком: `config.cities, criteria (w, must), custom, scores` |
| `GET /world/places?q=` | поиск по каталогу городов мира (65 тысяч, от 5 тысяч жителей) |
| `GET /world/numbers` | цифры от людей: зарплата на руки, аренда однушки, метр квартиры — `numbers[slug][kind] = { med, n }`, медиана в рублях, и курсы `fx` (рублей за единицу валюты) |

`who=residents` — только живущие сейчас и прожившие больше года. `source=site|chat_kyrillic|agent` — источник оценок,
можно несколько через запятую.

**Языки.** `/world/criteria` и `/world/cities` принимают `?lang=en`: названия критериев, групп, городов, стран и
регионов — на этом языке. Ключи (`key`, `slug`) от языка не зависят. Нет такого языка — ответ на русском, поле `lang`
в ответе скажет, на каком ответили. Комментарии людей — на том языке, на котором их написали.

Карта сайта для агентов — разделы, правила адресов, параметры таблицы: https://relocat.io/llms.txt.

## Города России в цифрах

У каждого из 200 городов relocat есть страница и её markdown-версия для агентов: `https://relocat.io/cities/<slug>.md` —
зарплаты, аренда, цены жилья, семья и дети, медицина, климат, экология, город, с единицами и пояснениями. Слаг —
из адреса страницы (`moskva`, `kazan`) или поле `relocat_slug` в `/world/cities`. По одному городу за запрос,
не чаще раза в секунду. Список всех городов с главными цифрами и слагами — `https://relocat.io/cities.md`.

## CSV — сразу таблицей

- Общая таблица с вашими весами:
  `GET /world/table/export.csv?w=sea:10,cost:8,winter:6&must=safety`
  — критерий без веса в `w` весит 5, `w=key:0` — не считается. `cities=slug,slug` — только эти города.
- Рейтинг человека: `GET /world/lists/{адрес}/export.csv`
- Параметры: `keys=1` — в заголовке ключи критериев вместо названий (удобно программам),
  `dec=comma` — дробная запятая, `bom=1` — метка UTF-8 для Excel.
- Формат: первая строка — заголовок (`place, slug, city, country, score, <критерии…>`), вторая —
  веса (`weight`), дальше города по баллу, последний столбец `url` — страница города с отзывами.
  `place` пусто у отсеянных по `must` и у городов без оценок. Без `keys=1` в конце файла ещё строка-источник.
- Цитируя или пересказывая данные, указывайте источник со ссылкой: «народный рейтинг городов relocat.io»
  и адрес страницы города или рейтинга.
- `export.xlsx` — то же в Excel: балл, отсев и место считаются формулами, веса — на отдельном листе.

## Примеры

```bash
# таблица целиком
curl -s 'https://api.relocat.io/api/v1/world/table' | jq '.cities[] | select(.slug=="tbilisi")'

# топ-10 для семьи у моря: CSV с ключами, балл уже посчитан
curl -s -H "Authorization: Bearer $KEY" 'https://api.relocat.io/api/v1/world/table/export.csv?keys=1&w=sea:10,baby:10,safety:9,cost:7&must=safety' | head -12

# что пишут про кофе в Тбилиси
curl -s 'https://api.relocat.io/api/v1/world/cities/tbilisi/feed?criterion=coffee&sort=top' | jq '.summary, .items[0:3][] | {score, comment}'

# рейтинг человека
curl -s 'https://api.relocat.io/api/v1/world/lists/kyrillic' | jq '.list | {title, cities: .config.cities}'
```


## Внести от имени человека — с ключом агента

Человек выдаёт ключ в профиле: relocat.io/profile/ → «Ключи для ИИ-агентов» — с названием агента и правами
(читать — всегда; оценки, цифры, рейтинги — если человек разрешил). Ключ передаётся заголовком `Authorization: Bearer <ключ>`, а модель, которой вы работаете, —
заголовком `X-Agent-Model` (например, `claude-opus-5-5` или `gpt-5.1`; можно полем `agent_model` в теле). Без модели запись не
примут (422 `agent_model_required`). Всё внесённое по ключу помечено «через <название агента> (<модель>)» и отфильтровывается (`?source=site` — только поставленное людьми на сайте,
`?source=agent` — только через агентов). Ключ открывает только рейтинг городов: профиль, вход и ключи ему закрыты.

Правила, чтобы рейтинг не превратился в свалку:
- **Оценки** — только городам из «Моих городов» человека и с тем опытом, что там указан: «живу» → `relation=now`,
  «жил» → `lived`, «бывал подолгу» → `trip` или `tourist`; срок `years` — не больше, чем выходит из лет в профиле.
  Иначе 422 `agent_city_not_in_profile`, `agent_relation_mismatch` или `agent_years_mismatch` — попросите человека
  поправить «Мои города». В средних такие оценки весят вполовину.
- **Цифры** (зарплата, аренда, цена метра) принимаются, но в медианы попадают после проверки модератором.
- **В сутки на ключ:** 30 запросов с оценками (один город за запрос), 30 — с цифрами, 20 — с рейтингами. Сверх — 429.

| Запрос | Что делает |
|---|---|
| `POST /world/ratings` `{ city, relation: now\|lived\|trip\|tourist, years: 0–3, items: [{ criterion, score: 1–5\|null, comment? }] }` | оценки города; `years`: 0 — до 3 месяцев, 1 — 3–12 месяцев, 2 — 1–3 года, 3 — больше 3 лет; `score: null` убирает оценку; комментарий до 140 знаков, без ссылок |
| `POST /world/numbers` `{ city, items: [{ kind, amount, currency, … }] }` | цифры: `salary` (на руки в месяц; `profession`, `experience` 0–3, `remote`), `rent1` (аренда в месяц; `rooms` 0–3, `area`, `district`), `buy_m2` (цена метра — или `total` + `area`; `market: new\|resale`); `year` — по умолчанию нынешний |
| `GET /me/world/ratings`, `GET /me/world/numbers` | что человек уже внёс |
| `GET\|PUT /me/world/cities` `{ cities: [slug…] }` | «мои города» человека |
| `POST /me/world/lists`, `PATCH /me/world/lists/{id}` | собрать и опубликовать рейтинг: `{ title, code?, about?, config: { cities, criteria: [{ key, w, must? }], custom, scores } }` |

Комментарий — слова самого человека: пишите его на том языке, на котором человек с вами говорит (русскоязычному —
по-русски), своими словами только сократите до 140 знаков, не переводите и не добавляйте своего мнения. То же для
`profession` и `district`. Вносите только то, что человек сам сказал: его опыт, его оценки, его цифры. Не придумывайте оценки за него
и не ставьте их городам, где он не жил.

## Условия

- Данные — для вас и ваших агентов: выбрать город, сравнить, ответить на вопрос, собрать свой рейтинг.
  Цитировать можно со ссылкой «по данным relocat.io» на `https://relocat.io/rating/` или страницу города.
- Будьте вежливы к серверу: не чаще 1 запроса в секунду, таблицу кэшируйте хотя бы на 5 минут — чаще она
  всё равно не меняется.
- Комментарии людей — их мнение: цитируйте коротко, с городом и критерием, без имён и без массовой
  перепубликации.
- Каталог городов мира (`/world/places`) — на основе GeoNames, CC BY 4.0.