API hujjati

REST API v1: reyting, tadqiqotchilar, ishlar va qidiruv; portal va jurnal platformalari uchun kalitlar, limitlar va namunalar.

Swagger UI OpenAPI JSON

Umumiy

REST API JSON qaytaradi; barcha yo'llar /v1/ prefiksi bilan.

Asosiy manzil: https://research.milliykengash.com/v1
Format: so'rov va javoblar JSON (Accept: application/json).
Til: ?lang=uz|ru|en — OTM va bo'linma nomlari tanlangan tilda (standart uz).
Vaqtlar ISO-8601 UTC (2026-09-16T09:10:00Z), sanalar YYYY-MM-DD.
Sahifalash: ?page=&page_size= (page_size ≤ 200); javobda items, total, page, page_size, next.

Sahifalangan javobjson

{
  "items": [ ... ],
  "total": 1234,
  "page": 1,
  "page_size": 50,
  "next": "/v1/rating/researchers?institution=12&page=2"
}

Autentifikatsiya va kalitlar

Ommaviy o'qish endpointlari kirishsiz ishlaydi. Integratsiyalar uchun API kalit beriladi.

Kirish turlari
Kirish	Kim uchun	Limit
ommaviy	Har kim: reyting, tadqiqotchi, ish va qidiruv endpointlari	IP bo'yicha daqiqasiga 120 so'rov
rating:read	milliykengash.com bosh portali — reyting va uning tarkibi (2-ustun)	Cheklanmagan
usage:write	journal.* va conference.* platformalari — ko'rish va yuklab olish hodisalari	So'rovda ≤ 1 000 hodisa

Kalit sarlavhada yuboriladi: Authorization: Bearer RESEARCH_API_KEY.
Kalitni MilliyKengash research administratori beradi; kalit faqat yaratilganda bir marta ko'rsatiladi va bazada xesh sifatida saqlanadi.
Kalitni brauzer kodida yoki ochiq repozitoriyda saqlamang — faqat server tomonida ishlating.

Limitlar

Limitlar xizmatni barcha foydalanuvchilar uchun barqaror saqlaydi.

Ommaviy endpointlar: bitta IP manzildan daqiqasiga 120 ta so'rov.
Limitdan oshsa — 429 javob va throttled xato kodi; Retry-After sarlavhasidagi vaqtdan keyin qayta urining.
API kalit bilan (rating:read) portal so'rovlari cheklanmaydi.

Kesh va ETag

Javoblar keshlanadi — ko'p so'raladigan ma'lumotni tez va arzon olish uchun ETag dan foydalaning.

Kesh muddati: reyting ro'yxatlari 60 soniya, sahifa ma'lumotlari 300 soniya (Cache-Control: public, max-age=…).
ETag: keyingi so'rovda If-None-Match sarlavhasini yuboring — ma'lumot o'zgarmagan bo'lsa 304 Not Modified qaytadi.
Jonli va snapshot: date parametrisiz reyting jonli (≤ 5 daqiqa kechikish); ?date=YYYY-MM-DD — o'sha kunning rasmiy snapshoti.

ETag bilan shartli so'rovshell

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

Endpointlar

To'liq sxema — OpenAPI hujjatida. Quyida asosiy endpointlar.

Reyting (portal va ommaviy)

Reyting (portal va ommaviy)
Endpoint	Tavsif	Kirish	Kesh
GET/v1/rating/institutions?region=&type=&date=&q=&lang=	OTM reytingi: o'rin, dinamika, R, 2-ustun, tarkib; date bo'lsa — snapshot	ommaviy	60 s
GET/v1/rating/institutions/{id}	OTM tarkibi, bo'linmalar reytingi, top-10 tadqiqotchi, yillar bo'yicha grafiklar	ommaviy	300 s
GET/v1/rating/institutions/{id}/history?from=&to=	OTM reytingi tarixi (kunlik snapshotlar)	ommaviy	300 s
GET/v1/rating/departments?institution=&level=	Fakultet va kafedralar reytingi (OTM ichida)	ommaviy	300 s
GET/v1/rating/units/{level}/{id}	Fakultet yoki kafedra sahifasi ma'lumotlari	ommaviy	300 s
GET/v1/rating/researchers?institution=&faculty=&department=&q=&page=	Tadqiqotchilar reytingi: H-indeks ↓, iqtiboslar ↓, ishlar ↓	ommaviy	60 s
GET/v1/methodology	Joriy metodologiya: parametrlar, versiyalar, manbalar	ommaviy	300 s

Ommaviy o'qish

Ommaviy o'qish
Endpoint	Tavsif	Kirish	Kesh
GET/v1/stats/overview	Umumiy hajmlar: OTM, tadqiqotchi, ish, iqtibos	ommaviy	300 s
GET/v1/sources	Ma'lumot manbalari holati va jadvali	ommaviy	300 s
GET/v1/filters	Viloyatlar, OTM turlari, yo'nalishlar, yillar oralig'i	ommaviy	300 s
GET/v1/search?q=&type=&year_from=&year_to=&institution=&subject=&page=	Ish, tadqiqotchi va OTM qidiruvi (lotin/kirill, DRI)	ommaviy	300 s
GET/v1/researchers/{milliy_id}	Tadqiqotchi profili, ko'rsatkichlari va o'rni	ommaviy	300 s
GET/v1/researchers/{milliy_id}/metrics	Tadqiqotchi ko'rsatkichlari (yopiq profilda ham ochiq)	ommaviy	300 s
GET/v1/researchers/{milliy_id}/works?sort=citations\|year&page=	Tadqiqotchi ishlari; yopiq profil → 403 profile_private	ommaviy	300 s
GET/v1/researchers/{milliy_id}/citations-by-year	Yillar bo'yicha iqtiboslar	ommaviy	300 s
GET/v1/researchers/{milliy_id}/cited-by?page=	«Kim iqtibos qilgan»; yopiq profil → 403	ommaviy	300 s
GET/v1/works/{dri}	Ish pasporti, ko'rsatkichlar (manba bo'yicha), havolalar	ommaviy	300 s
GET/v1/works/{dri}/metrics	Ish ko'rsatkichlari va oylik foydalanish	ommaviy	300 s
GET/v1/works/{dri}/citations	Ishning adabiyotlar ro'yxati va moslashtirish holati	ommaviy	300 s
GET/v1/works/{dri}/cited-by?page=	Shu ishga iqtibos bergan ishlar	ommaviy	300 s

Integratsiya va xizmat

Integratsiya va xizmat
Endpoint	Tavsif	Kirish	Kesh
POST/v1/usage/events	Ko'rish va yuklab olish hodisalarini qabul qilish (batch)	usage:write	—
GET/v1/openapi.json	OpenAPI 3 spetsifikatsiyasi	ommaviy	—
GET/v1/docs	Interaktiv Swagger hujjati	ommaviy	—
GET/v1/health	Xizmat holati	ommaviy	—

DRI yo'lda slash'lar bilan yoziladi: /v1/works/20.1042/talim/2026/v12_i3/48213907 — kodlash shart emas, har segment alohida kodlanishi mumkin.

Portal: reyting API

Bosh portal 2-ustunni shu endpointdan oladi. Kalit: rating:read.

So'rovshell

curl -s "https://research.milliykengash.com/v1/rating/institutions?lang=uz" \
  -H "Authorization: Bearer $RESEARCH_API_KEY" \
  -H "Accept: application/json"

Javob (qisqartirilgan)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 — o'rin va kechagi snapshotga nisbatan o'zgarish (musbat — ko'tarildi; kecha bo'lmasa null).
score_33 — 2-ustun balli (33,3 × R, 1 xona); R — research balli (0–1).
components — avg_h, downloads_ps, views_ps, normallashtirilgan H_n/Y_n/K_n va contrib hissalari.
method_version / computed_at — metodologiya versiyasi va oxirgi hisob vaqti; is_live — jonli yoki snapshot.

Kunlik rasmiy snapshotshell

curl -s "https://research.milliykengash.com/v1/rating/institutions?date=2026-09-15" \
  -H "Authorization: Bearer $RESEARCH_API_KEY"

Usage hodisalari

journal.* va conference.* platformalari sahifa ko'rishlari va PDF yuklab olishlarni batch bilan yuboradi. Kalit: usage:write.

So'rovhttp

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)" }
  ]
}

Javobjson

HTTP/1.1 202 Accepted

{
  "accepted": 2,
  "rejected": 1,
  "duplicates": 0,
  "errors": [
    { "index": 2, "code": "too_old", "message": "Hodisa 7 kundan eski" }
  ]
}

Batch: bitta so'rovda ko'pi bilan 1 000 hodisa; hodisalarni 5 daqiqa ichida yuboring.
Takrorlar: bir (dri, type, visitor_hash) 24 soat ichida faqat bir marta sanaladi (duplicates).
Vaqt: 7 kundan eski yoki 10 daqiqadan ortiq kelajakdagi hodisa rad etiladi (too_old, invalid).
Botlar referrer va user-agent belgilari bo'yicha rad etiladi (bot).
Idempotency-Key: bir xil kalit bilan 24 soat ichida qayta yuborilgan so'rovga oldingi javob qaytadi.
Maxfiylik: visitor_hash platformada hisoblanadi (IP saqlanmaydi) va qaytarib bo'lmaydigan bo'lishi shart.

Xatolar

Barcha xatolar bir xil formatda: kod, xabar, tafsilotlar va so'rov identifikatori.

Xato javobijson

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "profile_private",
    "message": "Tadqiqotchi profili yopiq",
    "details": []
  },
  "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Xato kodlari
HTTP	Kod	Ma'nosi
400	validation_error	Parametr noto'g'ri; details da maydon va sabab
401	not_authenticated	Kalit yoki sessiya talab qilinadi
403	permission_denied	Kalitda kerakli huquq (scope) yo'q
403	profile_private	Tadqiqotchi profili yopiq — ishlar va iqtibos beruvchilar ko'rsatilmaydi
404	not_found	Obyekt topilmadi
404	profile_merged	Profil boshqasiga birlashtirilgan; details da asosiy Milliy ID
404	snapshot_not_found	Bu sana uchun e'lon qilingan snapshot yo'q
429	throttled	So'rovlar limiti oshdi
500	server_error	Serverdagi ichki xato

Webhook

Kunlik snapshot e'lon qilinganda portalga xabar yuboriladi.

Imzoni tekshiring: so'rov tanasidan umumiy maxfiy kalit bilan HMAC-SHA256 hisoblang va X-Research-Signature sarlavhasi bilan solishtiring.

rating.snapshot.publishedhttp

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

01Umumiy

02Autentifikatsiya va kalitlar

03Limitlar

04Kesh va ETag

05Endpointlar