Документация API
REST API v1: рейтинг, исследователи, работы и поиск; ключи, лимиты и примеры для портала и журнальных платформ.
Общее
REST API возвращает JSON; все пути начинаются с префикса /v1/.
- Базовый адрес:
https://research.milliykengash.com/v1 - Формат: запросы и ответы в JSON (
Accept: application/json). - Язык:
?lang=uz|ru|en— названия вузов и подразделений на выбранном языке (по умолчанию uz). - Время — ISO-8601 UTC (
2026-09-16T09:10:00Z), даты —YYYY-MM-DD. - Пагинация:
?page=&page_size=(page_size ≤ 200); в ответеitems,total,page,page_size,next.
{
"items": [ ... ],
"total": 1234,
"page": 1,
"page_size": 50,
"next": "/v1/rating/researchers?institution=12&page=2"
}Аутентификация и ключи
Публичные эндпоинты чтения работают без входа. Для интеграций выдаются API-ключи.
- Ключ передаётся в заголовке:
Authorization: Bearer RESEARCH_API_KEY. - Ключ выдаёт администратор research MilliyKengash; ключ показывается один раз при создании и хранится в базе в виде хеша.
- Не храните ключ в браузерном коде или открытом репозитории — используйте его только на сервере.
Лимиты
Лимиты сохраняют стабильность сервиса для всех пользователей.
- Публичные эндпоинты: 120 запросов в минуту с одного IP-адреса.
- При превышении — ответ
429с кодом ошибкиthrottled; повторите после времени из заголовкаRetry-After. - С API-ключом (rating:read) запросы портала не ограничиваются.
Кэш и ETag
Ответы кэшируются — используйте ETag, чтобы быстро и дёшево получать часто запрашиваемые данные.
- Время кэша: списки рейтинга — 60 секунд, данные страниц — 300 секунд (
Cache-Control: public, max-age=…). - ETag: в следующем запросе отправьте заголовок
If-None-Match— если данные не изменились, вернётся304 Not Modified. - Живой рейтинг и снимок: без параметра
dateрейтинг живой (задержка ≤ 5 минут);?date=YYYY-MM-DD— официальный снимок за этот день.
curl -si "https://research.milliykengash.com/v1/works/20.1042/talim/2026/v12_i3/48213907"
# HTTP/1.1 200 OK
# Cache-Control: public, max-age=300
# ETag: "a1b2c3d4"
curl -si "https://research.milliykengash.com/v1/works/20.1042/talim/2026/v12_i3/48213907" -H 'If-None-Match: "a1b2c3d4"'
# HTTP/1.1 304 Not ModifiedЭндпоинты
Полная схема — в документе OpenAPI. Ниже основные эндпоинты.
Рейтинг (портал и публичный доступ)
Публичное чтение
Интеграция и служебные
DRI в пути пишется со слэшами:
/v1/works/20.1042/talim/2026/v12_i3/48213907 — кодировать не обязательно, можно кодировать каждый сегмент отдельно.Портал: API рейтинга
Главный портал получает 2-й столбец из этого эндпоинта. Ключ: rating:read.
curl -s "https://research.milliykengash.com/v1/rating/institutions?lang=uz" \
-H "Authorization: Bearer $RESEARCH_API_KEY" \
-H "Accept: application/json"{
"method_version": "2026.1",
"computed_at": "2026-09-16T09:10:00Z",
"snapshot_date": null,
"is_live": true,
"items": [
{
"rank": 1,
"delta_rank": 2,
"institution": {
"id": 12,
"portal_id": "otm-12",
"name": "Toshkent davlat pedagogika universiteti",
"short_name": "TDPU",
"region": "Toshkent shahri",
"type": "university"
},
"R": 0.76,
"score_33": 25.3,
"components": {
"avg_h": 6.0, "downloads_ps": 12.5, "views_ps": 100.0,
"H_n": 1.0, "Y_n": 0.166667, "K_n": 0.266667,
"contrib": { "h": 0.7, "downloads": 0.033333, "views": 0.026667 }
},
"staff_count": 412,
"works_count": 1830,
"citations": 5210,
"downloads": 5150.5,
"views": 41200.0
}
],
"total": 187,
"filters": {
"regions": ["Toshkent shahri", "Samarqand viloyati"],
"types": [{ "code": "university", "name": "Universitet" }]
}
}- rank / delta_rank — место и изменение относительно вчерашнего снимка (положительное — рост; если вчера нет —
null). - score_33 — балл 2-го столбца (33,3 × R, 1 знак); R — исследовательский балл (0–1).
- components — avg_h, downloads_ps, views_ps, нормированные H_n/Y_n/K_n и вклады
contrib. - method_version / computed_at — версия методологии и время последнего расчёта; is_live — живой рейтинг или снимок.
curl -s "https://research.milliykengash.com/v1/rating/institutions?date=2026-09-15" \
-H "Authorization: Bearer $RESEARCH_API_KEY"События использования
Платформы journal.* и conference.* пакетами отправляют просмотры страниц и скачивания PDF. Ключ: usage:write.
POST https://research.milliykengash.com/v1/usage/events
Authorization: Bearer <usage:write>
Idempotency-Key: 5f0c2d1e-journal-2026-09-16T10:20
Content-Type: application/json
{
"source": "journal",
"events": [
{ "dri": "20.1042/talim/2026/v12_i3/48213907", "type": "view",
"ts": "2026-09-16T10:15:00+05:00", "visitor_hash": "sha256(ip+ua+salt)",
"referrer": "https://google.com" },
{ "dri": "20.1042/talim/2026/v12_i3/48213907", "type": "download",
"ts": "2026-09-16T10:16:10+05:00", "visitor_hash": "sha256(ip+ua+salt)" }
]
}HTTP/1.1 202 Accepted
{
"accepted": 2,
"rejected": 1,
"duplicates": 0,
"errors": [
{ "index": 2, "code": "too_old", "message": "Hodisa 7 kundan eski" }
]
}- Пакет: не более 1 000 событий в одном запросе; отправляйте события в течение 5 минут.
- Повторы: одна тройка (dri, type, visitor_hash) учитывается раз в 24 часа (
duplicates). - Время: события старше 7 дней или более чем на 10 минут в будущем отклоняются (
too_old,invalid). - Боты отклоняются по признакам referrer и user-agent (
bot). - Idempotency-Key: на повторный запрос с тем же ключом в течение 24 часов возвращается прежний ответ.
- Конфиденциальность:
visitor_hashвычисляется на платформе (IP не хранится) и должен быть необратимым.
Ошибки
Все ошибки в одном формате: код, сообщение, детали и идентификатор запроса.
HTTP/1.1 403 Forbidden
{
"error": {
"code": "profile_private",
"message": "Tadqiqotchi profili yopiq",
"details": []
},
"request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}Вебхук
При публикации ежедневного снимка на портал отправляется уведомление.
Проверьте подпись: вычислите HMAC-SHA256 от тела запроса с общим секретом и сравните с заголовком X-Research-Signature.
POST <PORTAL_WEBHOOK_URL>
X-Research-Signature: sha256=<HMAC(body, PORTAL_WEBHOOK_SECRET)>
Content-Type: application/json
{
"event": "rating.snapshot.published",
"date": "2026-09-16",
"method_version": "2026.1",
"url": "/v1/rating/institutions?date=2026-09-16"
}