أجرِ أول طلب Narwhal API لك

استخدم مفتاحاً واحداً لـEconomics وFX وEquities وإيداعات SEC وأسعار نخيل الزيت والتقاويم عبر REST أو MCP.

يبدأ هذا الدليل بـCPI، ثم يربط بمرجع عملي لكل واحد من APIs الستة عند api.narwhalapi.com.

تغطية البيانات الاقتصادية

AUS وCAN وDEU وFRA وGBR وJPN وMYS وNLD وSGP وUSA متاحة مباشرةً. يتطلب كل طلب بيانات مفتاح Narwhal API.

حدود الإصدار التجريبي المجاني: 3,000 الطلبات الناجحة لكل شهر وفق UTC، بالإضافة إلى 30 طلبًا في الدقيقة مع دفعة قدرها 5تشترك 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",
  "base_period": "1982-84",
  "base_value": "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 والتضخم والعمل والناتج المحلي الإجمالي والتجارة من ناشرين رسميين في عشر دول.
FX API	الأسعار الحالية والتحويل والسجل المرقّم بصفحات، مع طابع زمني لكل سعر.
واجهة API للأسهم	اكتشف أدوات الأسهم العادية واسترد الأشرطة اليومية المعدلة للتقسيم.
واجهة تقويم العطلات الرسمية API	عطلات رسمية منشورة مع نطاق وطني وإقليمي ونطاق للأيام البديلة.
واجهة Palmoil FFB API	جداول FFB الإندونيسية الرسمية حسب المنطقة وعمر الشجرة.
واجهة SEC Filings API	البحث عن الشركات والهوية وبيانات إيداعات SEC الوصفية.

اختر دولة ومؤشرًا

تتوفر تسع عمليات لأحدث إصدار وتسع عمليات تاريخية مطابقة لكل دولة متاحة مباشرة. و مرجع واجهة API للاقتصاد يسرد كل مسار وشكل استجابة.

المؤشر	لاحقة المسار
CPI	`/cpi`
التضخم	`/inflation`
البطالة	`/unemployment`
المشاركة في القوى العاملة	`/labour-force-participation`
GDP والنمو	`/gdp` · `/gdp-growth`
التجارة والصادرات والواردات	`/trade` · `/trade/exports` · `/trade/imports`

الاتصال عبر MCP

استخدم المفتاح والمخططات نفسيهما مع عميل MCP. يسرد اكتشاف الأدوات العمليات المتاحة لحسابك عبر APIs الستة. راجع الـ دليل 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 يستهلك طلبًا واحدًا.

اقرأ الاستجابة

اقرأ مخطط استجابة كل عملية. تعيد البيانات الاقتصادية كائن نطاق؛ بينما تستخدم الأسهم meta/values للسلاسل الزمنية و count/data للأدوات.

قاعدة	ما يعنيه ذلك
`period`	الشهر أو الربع أو السنة الرسمية الدقيقة التي أعادها الإصدار.
`released_on`	تاريخ النشر الرسمي.
سلاسل عشرية	تتجنب القيم مفاجآت الفاصلة العائمة الثنائية.
البيانات المفقودة	تفشل الإصدارات غير المكتملة أو غير المتاحة بشكل مغلق؛ ولا تتحول المفقودات إلى صفر.

اقرأ كيف يخزن Narwhal الإصدارات الرسمية ويحدّثها.

ترويسات الحصة في الاستجابات الناجحة

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

تعامل مع الأخطاء حسب الحالة والرمز

تحقّق من حالة HTTP أولًا، ثم استخدم code في منطق التطبيق. detail مخصص للسجلات وتصحيح الأخطاء. أما الـ دليل الأخطاء والحصة يسرد كل حالة عامة.

استجابة مشكلة RFC 9457

{
  "ok": false,
  "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",
  "instance": "/v1/economics/USA/cpi"
}

هل تحتاج مساعدة بشأن مفتاح؟ اتصل بواجهة Narwhal API.

راجع المستجدات في سجل التغييرات.

LLM؟ اقرأ llms.txt.