कन्वेंशन: एनवेलप, कैटेगरी, पेजिंग और त्रुटियाँ

ये नियम एक बार सीख लें, फिर हर endpoint आपकी उम्मीद के मुताबिक़ व्यवहार करेगा।

रिस्पॉन्स एनवेलप

हर सफल रिस्पॉन्स दो कुंजियों वाला JSON ऑब्जेक्ट होता है:

कुंजी	सामग्री
data	ऑब्जेक्ट (एकल रिसोर्स) या ऐरे (सूची)
meta	total, page, size, total_pages; endpoint पेज्ड न होने पर पेजिंग फ़ील्ड null होते हैं

{
  "data": { "year": 2026, "status": "ACTIVE" },
  "meta": { "total": 1, "page": null, "size": null, "total_pages": null }
}

फ़ील्ड के नाम हर जगह snake_case में हैं (rider_number, total_points, season_year)।

कैटेगरी: MotoGP, Moto2 और Moto3

सीज़न-आधारित endpoints category क्वेरी पैरामीटर स्वीकार करते हैं, जिसका मान MOTOGP, MOTO2 या MOTO3 होता है। class उन्हीं मानों वाला उपनाम है; दोनों में से एक ही भेजें, दोनों नहीं।

GET /standings/seasons/2026/riders?category=MOTO2
GET /races/seasons/2026?category=MOTO3

category स्पष्ट रूप से दें, ताकि नतीजा किसी डिफ़ॉल्ट पर निर्भर न रहे।

पेजिंग

“सब कुछ पाएँ” वाले endpoints, यानी /riders, /teams, /races और /standings, page (1 से शुरू) और size (1–200, डिफ़ॉल्ट 20) से पेज्ड हैं:

GET /riders?page=2&size=50

"meta": { "total": 118, "page": 2, "size": 50, "total_pages": 3 }

page के total_pages तक पहुँचने तक लूप चलाएँ:

async function getAll(path) {
  const rows = [];
  for (let page = 1; ; page++) {
    const { data, meta } = await getEnvelope(`${path}?page=${page}&size=200`);
    rows.push(...data);
    if (!meta.total_pages || page >= meta.total_pages) return rows;
  }
}

/riders/seasons/{year} जैसी सीज़न-आधारित सूचियाँ पूरा सीज़न एक ही रिस्पॉन्स में लौटाती हैं।

क्रम

स्टैंडिंग्स position के क्रम में आती हैं। कैलेंडर और रेस नतीजों का क्रम तय नहीं होता, इसलिए उन्हें खुद सॉर्ट करें:

races.sort((a, b) => a.round_number - b.round_number);
results.sort((a, b) => a.position - b.position);

आइडेंटिफ़ायर

रिसोर्स	किससे खोजें
राइडर	रेस नंबर: /riders/{rider_number} (जैसे 93)
टीम	किसी भी टीम सूची से मिली ओपेक ID: /teams/{id}, या नाम से: /teams/name/{name}
रेस	सीज़न + राउंड: /races/seasons/{year}/round/{round}, या ओपेक ID: /races/{race_id}/results
सीज़न	वर्ष: /seasons/{year}

ओपेक ID ("82MQRdM5q7ub4OSm6Jhx") को हार्ड-कोड करने के बजाय सूची वाले रिस्पॉन्स से लें, और टीमों को नाम की जगह ID से मिलाएँ, क्योंकि स्पॉन्सर के नाम हर सीज़न बदलते रहते हैं।

स्टैंडिंग के प्रकार

समर्पित रूट (/riders, /teams, /manufacturers, /bmw-m) के अलावा आप प्रकार के आधार पर भी स्टैंडिंग टेबल माँग सकते हैं:

GET /standings/seasons/2026/type/MANUFACTURER?category=MOTOGP

प्रकार हैं RIDER, TEAM, MANUFACTURER और BMW_M।

त्रुटियाँ

त्रुटियों में मानक HTTP स्टेटस कोड और JSON बॉडी होती है:

{
  "timestamp": "2026-01-27T19:18:29",
  "status": 404,
  "error": "Not Found",
  "message": "Rider not found with number: 99",
  "path": "/riders/99"
}

स्टेटस	अर्थ	क्या करें
400	अमान्य पैरामीटर (ग़लत वर्ष, अज्ञात कैटेगरी)	रिक्वेस्ट सुधारें; होने पर validation_errors में समस्याएँ सूचीबद्ध होती हैं
401 / 403	RapidAPI कुंजी ग़ायब या अमान्य, या सब्सक्रिप्शन नहीं	दोनों हेडर और अपना प्लान जाँचें
404	राइडर, टीम, रेस या सीज़न मौजूद नहीं है	”नहीं मिला” स्थिति दिखाएँ
429	आपके प्लान की रेट लिमिट या कोटा पूरा हो गया	रुकें और बाद में दोबारा कोशिश करें, या प्लान अपग्रेड करें
5xx	अस्थायी सर्वर समस्या	एक्सपोनेंशियल बैकऑफ़ के साथ दोबारा कोशिश करें; स्टेटस पेज देखें

कैशिंग

हर रेस वीकेंड के बाद नतीजे और स्टैंडिंग्स बदलते हैं, और प्रोफ़ाइल सीज़न के बीच बदलती हैं। कोटा बचाने और पेज तेज़ रखने के लिए जमकर कैश करें:

डेटा	सुझाया गया कैश समय
सीज़न, राइडर, टीम, करियर आँकड़े	24 घंटे
कैलेंडर	12 घंटे
नतीजे और स्टैंडिंग्स	रेस वीकेंड पर 1 घंटा, बाक़ी समय 12 घंटे

अपनी कुंजी सर्वर पर रखें

आपकी RapidAPI कुंजी बिलिंग क्रेडेंशियल है। API को अपने बैकएंड, serverless फ़ंक्शन या बिल्ड स्टेप से कॉल करें, कभी ऐसे ब्राउज़र या मोबाइल कोड से नहीं जो कुंजी को यूज़र्स तक पहुँचा दे। स्टैंडिंग्स टेबल गाइड में कैशिंग वाला एक छोटा प्रॉक्सी दिखाया गया है।