# NameCandies — полное описание для агентов

Справочник личных имён с публичным JSON-RPC API. Ниже — как вызывать API
и перечень методов. Машиночитаемое описание: https://namecandies.gumeniuk.com/rpc/openrpc.json

## Вызов API

Эндпоинт: POST https://namecandies.gumeniuk.com/rpc
Content-Type: application/json
Авторизация: не требуется (публичные read-методы).
Лимит: 60 запросов в минуту с одного IP (код ошибки 1429).

Пример:

    curl -s https://namecandies.gumeniuk.com/rpc -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"names.get","params":{"slug":"alena"}}'

Нормализация ввода: регистр, ё/е и латинская транслитерация сводятся к одному
имени («алёна» = «алена» = «Alena»).

## Методы

### cultures.list
Справочник происхождений
Все культуры/традиции происхождения с числом имён.

### namedays.byDate
Именины на дату
Имена с именинами в указанный день по православному месяцеслову (курированное ядро, покрытие неполное).
Параметры: month (integer) — обязательный, day (integer) — обязательный

### names.filter
Подбор имён по фильтрам
Фильтры: пол, культура, первая буква, длина, редкость, сортировка. Пагинация — keyset-курсором (next_cursor), общего количества нет. Редкость считается по данным US SSA 1880–2008.
Параметры: gender (string), culture_code (string), letter (string), min_len (integer), max_len (integer), rarity (string), sort (string), cursor (string), limit (integer)

### names.get
Полная карточка имени
Возвращает всё об одном имени: написания, значение, происхождение, связанные имена, именины и популярность. Укажите ровно один идентификатор: slug или public_id.
Параметры: slug (string), public_id (string)

### names.search
Поиск имени
Двухфазный поиск: точное/префиксное совпадение по нормализованному написанию, затем похожие (trigram). Регистр, ё/е и латинская транслитерация нормализуются: «Алёна», «алена» и «Alena» находят одно имя.
Параметры: query (string) — обязательный, limit (integer)

### names.similar
Похожие имена
До 8 имён, близких по звучанию и того же пола.
Параметры: public_id (string) — обязательный, limit (integer)

### popularity.series
Динамика популярности
Ряд популярности имени по годам. ИСТОЧНИК: данные США (SSA), 1880–2008 — не российская статистика; трактуйте с этой оговоркой.
Параметры: public_id (string) — обязательный

### rpc.discover
Return the service's OpenRPC description
The service-discovery method from the OpenRPC specification: returns the OpenRPC 1.3.2 document describing every public method, its param/result schemas, and its documentation.

## Оговорки об источниках

- meanings часто пусты: значение известно не для всех имён, мы его не выдумываем.
- popularity — данные США (SSA), 1880–2008; не российская статистика.
- namedays — курированное ядро православного месяцеслова, покрытие неполное.
- relations.cognates — полуавтоматические кандидаты, возможен шум.
- Данные предоставляются «как есть», без гарантий.