Skip to content
Public API · v1

Pokékipe Public API

تحليلات Pokémon تنافسية مجانية، مشتقة من إحصاءات Smogon الشهرية وتتحدَّث كل شهر. ما يحتاج حساب للاستخدام العادي؛ سوِّ مفتاح شخصي من Account Settings لرفع سقف rate-limit للسحب بكميات.

Quickstartافتح الـ reference

  • Endpoints

    100+

  • الفورمات

    30+

  • التحديث

    شهري

  • Auth

    اختياري

  • الترخيص

    CC BY 4.0

ليش هذا موجود

وش هذا الـ API، ووش مو

أربع أشياء تعرفها قبل ما تكتب سطر كود واحد ضد /api/v1/.

وش هذا الـ API

سطح JSON للقراءة فقط فوق بيانات Pokémon التنافسية بالعالم. اسأل "وش الميتا في Gen 9 OU عند 1500+ ELO هذا الشهر؟" أو "مَن كاونتر هذا الـ Pokémon في top cut هذي البطولة؟" واحصل على إجابة بـ call واحد بأشكال ثابتة وموثَّقة.

منين تجي البيانات

سجلات معارك Smogon الشهرية (الـ chaos JSON العام)، تغذيات البطولات الرسمية (Pokémon Company، VGC، Smogon Tour)، ومصادر المجتمع مثل Limitless TCG لأحداث المجتمع. Pokékipe يشغِّل pipeline خاصته لـ ingestion وnormalization وenrichment فوقها، ثم يعرض النتيجة المنظَّفة من جديد.

وش هذا الـ API مو

مو جسر Pokémon Showdown مباشر، مو محاكي معارك، مو endpoint لحاسبة damage، مو محرك teambuilding. الأدوات هذي عايشة على الموقع. الـ API هو طبقة البيانات اللي يقعدون عليها.

اعتراف بالمصدر

الفضل لأهله. Smogon، ومصدِّرو chaos-format JSON، ومجتمع اللاعبين اللي يلعبون كل شهر، هم السبب إن هذي البيانات موجودة. Pokékipe يخليها قابلة للاستعلام؛ ما يملك البيانات الأصلية.

ابدأ

أول call، في 30 ثانية

ثلاث أمثلة copy-paste تجيب كتالوج الفورمات. بلا API key، بلا setup، بلا تسجيل. اختر تبويب لغتك، الصق، شغِّل.

curl -s https://pokekipe.com/api/v1/formats \
  | jq '.[0:3]'

بدِّل المسار بأي endpoint مذكور في الـ reference تحت. أول call المفروض يرجع في أقل من ثانية على cache دافي.

المصادقة

المصادقة وحدود المعدل

الاستدعاءات المجهولة تشتغل للاستخدام العادي. مفتاح شخصي (مجاني، يُولَّد من إعدادات حسابك) يرفع سقف rate-limit للمحللين وبناة الأدوات اللي يسحبون البيانات بكميات. المفاتيح لا تفتح endpoints جديدة أبدًا؛ هي فقط ترفع السقف.

Anonymous، بلا مفتاح

افتراضي

سوِّ calls بلا أي header. الـ bucket مرتبط بـ IP تبعك، فسكربت صغير أو LLM agent يسوي شوية طلبات في كل session ما راح يضرب الحد أبدًا.

  • بلا حساب، بلا تسجيل، بلا header تضبطه.
  • Bucket لكل IP، مناسب لسكربتات عابرة واستخدام أدوات LLM agent.
  • تضرب 429 لو واصلت سحب بكميات؛ بدِّل لمفتاح شخصي.

في الدقيقة

60

في اليوم

5,000

Authenticated، مع مفتاح شخصي

موصى به للسحب بكميات

مرِّر مفتاحك كـ X-API-Key (أو Authorization: Bearer pk_live_…). الاستدعاءات المجهولة تستمر تشتغل جنبه؛ المفتاح يرفع السقف فقط، ما يفتح endpoints جديدة.

  • Bucket لكل user: تغيُّر IP تبعك ما يصفِّر العداد.
  • سقوف أعلى على كل حد per-route.
  • حتى 5 مفاتيح فعالة لكل حساب، قابلة للإلغاء أي وقت.

في الدقيقة

600

في اليوم

100,000

ولِّد API key

Headers على كل استجابة

كل استجابة ناجحة تحمل rate-limit headers تحت عشان الـ client تبعك يضبط تيمبوه بنفسه بدون retries. اقرأها مرة وحدة لكل استجابة وخفِّض السرعة لحظة ما يوصل Remaining لعدد طلبات قليل، مو لصفر.

Headerالمعنى
X-RateLimit-Tierأي tier أنت فيه: anonymous (بلا مفتاح) أو authenticated (JWT أو API key محلول).
X-RateLimit-Limit-Minالسقف بالدقيقة لتيرك (60 anonymous، 600 authenticated).
X-RateLimit-Limit-Dayالسقف اليومي لتيرك (5 000 anonymous، 100 000 authenticated).
X-RateLimit-Remaining-Minالاستدعاءات المتبقية في نافذة الدقيقة الحالية. خفِّض السرعة لما يقرب من الصفر.
X-RateLimit-Remaining-Dayالاستدعاءات المتبقية في نافذة اليوم الحالي. تتصفَّر في نفس دقيقة الساعة كل يوم.
Retry-Afterيُرسل فقط على 429. انتظر هذي الثواني قبل ما تعيد المحاولة، عادةً تحت 60 لنافذة الدقيقة.

الأخطاء

الأخطاء اللي ممكن تشوفها

أكواد HTTP status معيارية. الـ body دائمًا JSON مع حقل "detail" يوصف وش صار غلط. تعامل مع 4xx كمشكلة عقد (طلبك أنت) و5xx كمشكلتنا (أعد المحاولة مع backoff).

200

OK

OK. الـ body هو JSON payload الموثَّق في الـ reference. المصفوفات الفارغة تعني "ما فيه صفوف"، مو "مفقود"، تعامل معها كبيانات، مو كفشل.

304

Not Modified

Not Modified. تم التحقق من cache headers. استخدم الـ body المخزَّن، ما يحتاج re-parse. يُرجَع تلقائيًا لما ترسل If-None-Match أو If-Modified-Since.

400

Bad Request

Bad Request. query parameter أو شكل الـ body غلط. رسالة detail تذكر الحقل المحدد بالضبط. ما تعيد المحاولة بدون ما تصلح الـ input.

401

Unauthorized

Unauthorized. الطلب يحتاج API key أو session وما حصل على أي منهم، أو الـ credentials غير صالحة/ملغاة. لا تستمر في إطلاق الطلبات، أعد إصدار الـ credential.

404

Not Found

Not Found. المسار أو الـ resource غير موجود. للـ routes الخاصة بكل Pokémon، هذا غالبًا يعني إن الفورمات ما عنده usage data للـ Pokémon هذا، مو خطأ إملائي من طرفك.

429

Too Many Requests

Too Many Requests. ضربت سقف rate-limit. اقرأ Retry-After وانتظر، exponential backoff إتيكيت ممتاز بس نادرًا يحتاج لأن النافذة قصيرة.

500

Server Error

Internal Server Error. صار شي عندنا. أعد المحاولة مرة واحدة بعد ثواني؛ لو استمر، كلِّمنا على Discord مع رابط الطلب.

503

Service Unavailable

Service Unavailable. إما نسوي deploy أو محمَّلين زيادة مؤقتًا. أعد المحاولة مع backoff. تحديثات الحالة تتنشر على Discord المجتمع.

القواعد الأساسية

شروط الاستخدام

أربع قواعد أساسية. اقرأها مرة، وفِّر على نفسك المستقبلية رسالة Discord.

اعتراف بالمصدر

العزو مطلوب لما تعيد التوزيع أو النشر. اذكر Pokékipe (رابط لـ https://pokekipe.com)، واذكر Smogon لـ chaos JSON الأصلي اللي ينشرونه كل شهر.

أفضل جهد، بلا SLA

أفضل جهد، بلا SLA. البيانات تُقدَّم "كما هي" بلا ضمان uptime. caching بشدة وdegrade بسلاسة لما endpoint يكون بطيء أو يرجع 429.

إدارة الإصدارات

Schemas تحت /api/v1/ تبقى backwards-compatible خلال دورة حياة v1. التغييرات المكسِّرة تروح لـ /api/v2/ مع إشعار مسبق على Discord وsunset header على المسار المهجور.

الاستخدام التجاري

الاستخدام التجاري مسموح تحت CC BY 4.0. لو بنيت شي فوق هذا الـ API، نحب نسمع عنه على Discord المجتمع.

Reference · OpenAPI 3حي، ثلاث لوحات

تصفَّح كل endpoint، كلها في مكان واحد

تصفَّح كل endpoint مع الأوصاف، جداول البارامترات، schemas الطلب والاستجابة، وأمثلة كود بـ curl وJavaScript وPython. ابحث في الـ API كله من خانة وحدة، deep-link لأي عملية، شارك الـ URL.

  • 100+ endpoints
  • ·
  • 3-pane تنقُّل، محتوى، أمثلة
  • ·
  • بحث نصّي شامل
  • ·
  • أمثلة طلبات حية
افتح الـ reference الكاملأو خذ سبيك OpenAPI 3 الخام