التوثيق
أجرِ أول طلب Narwhal API لك
ابدأ بمفتاح API واحد للوصول إلى الاقتصاد وأسعار الصرف وأسعار السلع الفورية (الذهب والفضة والبلاتين والبلاديوم والنحاس وخام WTI وخام برنت) وزيت النخيل وأسعار البنزين الأسبوعية في الولايات المتحدة (EIA) وأسعار الديزل الأسبوعية في الولايات المتحدة (EIA) والأسعار المرجعية الشهرية للسلع (World Bank) والأسعار الفورية اليومية (خام WTI وخام برنت والغاز الطبيعي) ومنحنيات العائد في الولايات المتحدة والمملكة المتحدة وألمانيا واليابان وكندا واحتمالات أسواق التنبؤ (Kalshi وPolymarket) وتقويمات إصدار البيانات الاقتصادية والإجازات الرسمية. تعرّف على المصادقة بمفتاح Bearer وكيفية التعامل مع الاستجابات والأخطاء.
يبدأ هذا الدليل بمؤشر CPI، ثم يربطك بمراجع واجهات API المتاحة على api.narwhalapi.com.
36 الدول: AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA. تختلف التغطية حسب العملية والدولة. تسرد كل عملية الدول المدعومة. يحتاج كل طلب بيانات إلى مفتاح Bearer.
حدود الإصدار التجريبي لخطة Free: 5,000 طلب ناجح لكل شهر بتوقيت UTC، بالإضافة إلى 30 طلبًا في الدقيقة. تشترك REST وMCP في الحدود نفسها.
إعداد مفتاح API الخاص بك
أرسل المفتاح باعتباره رمز Bearer في ترويسة Authorization ؛ ولا تضعه في عنوان URL أبدًا. أنشئ حسابًا للحصول على مفتاح مجاني، ثم اقرأ دليل المصادقة قبل تخزينه.
export NARWHAL_API_KEY="nw_live_..."طلب مؤشر أسعار المستهلك الرسمي
مرّر رمز الدولة ISO المؤلف من ثلاثة أحرف في المسار. وحذف period يعيد أحدث إصدار كامل مقبول.
curl --request GET \
--url https://api.narwhalapi.com/v1/economics/USA/cpi \
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"country": "USA",
"period": "2026-07",
"value": "333.918",
"index_base": "1982-84=100",
"released_on": "2026-08-12"
}أمثلة Python وJavaScript
استخدم متغير البيئة ونقطة النهاية نفسيهما في تطبيقك. تستخدم هذه الأمثلة المكتبات المدمجة.
Python 3
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.narwhalapi.com/v1/economics/USA/cpi",
headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
data = json.load(response)
print(data)JavaScript · Node.js 18+
const key = process.env.NARWHAL_API_KEY;
if (!key) throw new Error("Set NARWHAL_API_KEY first");
const response = await fetch(
"https://api.narwhalapi.com/v1/economics/USA/cpi",
{ headers: { Authorization: "Bearer " + key }, signal: AbortSignal.timeout(30000) }
);
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);اختر واجهة API الخاصة بك
| API | ابدأ بـ |
|---|---|
| واجهة API للاقتصاد | بيانات CPI والتضخم وسوق العمل وGDP والتجارة من ناشرين رسميين. تختلف التغطية حسب الدولة والمؤشر. |
| واجهة API لأسعار الصرف | الأسعار الحالية والتحويل والسجل المقسّم إلى صفحات، مع طابع زمني لكل سعر. |
| واجهة API للعطلات الرسمية | إجازات رسمية منشورة مع تحديد نطاقها الوطني والإقليمي والأيام المعتمدة للاحتفال بها. |
| واجهة API لزيت النخيل | أسعار CPO وFFB من إندونيسيا وماليزيا، بوحداتها الأصلية وبياناتها التاريخية. |
اختر دولة ومؤشرًا
تتوفر عمليات أحدث إصدار وعمليات تاريخية مطابقة، مع اختلاف المؤشرات المتاحة حسب الدولة. و مرجع واجهة API للاقتصاد يسرد كل مسار وشكل استجابة.
| المؤشر | لاحقة المسار |
|---|---|
| مؤشر أسعار المستهلك | /cpi |
| التضخم | /inflation |
| البطالة | /unemployment |
| المشاركة في القوى العاملة | /labour-force-participation |
| الناتج المحلي الإجمالي والنمو | /gdp · /gdp-growth |
| التجارة | /trade |
الاتصال عبر MCP
استخدم المفتاح والمخططات نفسيهما مع عميل MCP. يسرد اكتشاف الأدوات العمليات المتاحة لحسابك عبر واجهات API الأربع. راجع دليل MCP.
{
"url": "https://api.narwhalapi.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_NARWHAL_API_KEY"
}
}استبدل العنصر النائب من خلال إعداد السر الآمن في عميل MCP الخاص بك. لا يوسّع JSON العادي متغيرات البيئة تلقائياً.
{
"method": "tools/call",
"params": {
"name": "fx_get_rates",
"arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
}
}التهيئة و tools/list لا تستهلك الحصة. كل استدعاء ناجح tools/call يستهلك طلبًا واحدًا.
اقرأ الاستجابة
اقرأ مخطط استجابة كل عملية قبل التكامل.
| قاعدة | ما يعنيه ذلك |
|---|---|
period | الشهر أو الربع أو السنة الرسمية الدقيقة التي أعادها الإصدار. |
released_on | تاريخ النشر الرسمي. |
| سلاسل نصية لأعداد عشرية | تتجنب القيم مفاجآت الفاصلة العائمة الثنائية. |
| البيانات المفقودة | تُحجب الإصدارات غير المكتملة أو غير المتاحة؛ ولا تُحوَّل البيانات المفقودة إلى أصفار. |
اقرأ كيف يخزن Narwhal الإصدارات الرسمية ويحدّثها.
ترويسات الحصة في الاستجابات الناجحة
X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Resetتعامل مع الأخطاء حسب الحالة والرمز
تحقّق من حالة HTTP أولًا، ثم استخدم code في منطق التطبيق. detail مخصص للسجلات وتصحيح الأخطاء. أما دليل الأخطاء والحصة فيسرد كل حالة عامة.
{
"type": "https://narwhalapi.com/problems/invalid-query",
"title": "Invalid query",
"status": 400,
"detail": "The request parameters are not valid for this operation.",
"code": "invalid_query",
"request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50"
}المساعدة والموارد
هل تحتاج مساعدة بشأن مفتاح؟ تواصل مع Narwhal API.
راجع المستجدات في سجل التغييرات.
LLM؟ اقرأ llms.txt.