EconMetrics

توثيق واجهة برمجة التطبيقات

الوصول إلى البيانات الاقتصادية السعودية برمجياً عبر واجهة EconMetrics REST API.

الرابط الأساسي

تُقدَّم جميع النقاط أدناه من هذا الرابط الأساسي. أضِف معامل اللغة (en أو ar) حيثما كان مدعوماً.

https://econmetrics.dev.shibli.me/em-api

المصادقة

نقاط التصفح العامة تعمل دون بيانات اعتماد:

  • /v1/series
  • /v1/series/facets
  • /v1/series/featured
  • /v1/series/latest?series_ids={id}
  • /v1/series/{id}
  • /v1/series/{id}/children
  • /v1/series/{id}/related
  • /v1/series/{id}/regions
  • /v1/series/{id}/partners
  • /v1/series/{id}/forecast
  • /v1/series/{id}/observations?preview=true
  • /v1/series/compare?series_ids={ids}&preview=true
  • /v1/series/rankings
  • /v1/datasets
  • /v1/datasets/{slug}
  • /v1/datasets/{slug}/series
  • /v1/datasets/{slug}/facets
  • /v1/datasets/{slug}/tree
  • /v1/datasets/{slug}/state
  • /v1/indicators
  • /v1/indicators/{slug}
  • /v1/catalog/filters
  • /v1/calendar
  • /v1/calendar.ics
  • /v1/coverage
  • /v1/source-agencies
  • /v1/source-agencies/{agency_id}/logo

الأسطح المقيّدة تتطلب مفتاح API أو رمز جلسة مستخدم — السجل الكامل للملاحظات خارج نافذة المعاينة، وتنزيلات .csv و .xlsx، ومفاتيح API، والسلاسل المحفوظة، وWebhooks، والمؤسسات، والفوترة، ومسارات الحساب، و/admin:

  • X-API-Key: em_… — مفاتيح API للوصول البرمجي، تُنشأ من لوحة التحكم (الخطة الاحترافية) -- ويلزم المفتاح للسجل الكامل للملاحظات وتنزيل CSV وXLSX.
  • Authorization: Bearer … — رموز الجلسة من POST /auth/login أو /auth/register.

إدارة مفاتيح API من لوحة التحكم.

بدء سريع

يعمل المثالان أدناه كما هما، دون مفتاح: يستخدم المثال السلسلة SA.CPI.CAT.00.YOY المنشورة فعليًا. استخدم q= للبحث في السلاسل بالاسم أو المعرف، وpreview=true لنافذة الملاحظات العامة؛ أما السجل الكامل وCSV وXLSX فتحتاج مفتاح الخطة الاحترافية (Pro).

import requests

API = "https://econmetrics.dev.shibli.me/em-api"

# The two calls below are public -- no API key required.
# SA.CPI.CAT.00.YOY is a real published series (GASTAT: CPI, year-on-year % change).
# List published series (name or id search via q=)
series = requests.get(
    f"{API}/v1/series",
    params={"q": "CPI", "published_only": "true"},
).json()

# Fetch observations for one series
# preview=true returns the public window on a published series.
# Full history, CSV and XLSX need a Pro API key.
obs = requests.get(
    f"{API}/v1/series/SA.CPI.CAT.00.YOY/observations",
    params={"preview": "true"},
).json()

مواصفة OpenAPI التفاعلية

جرّب كل نقطة مباشرة مع مخططات الطلب والاستجابة من توثيق OpenAPI التفاعلي:

https://econmetrics.dev.shibli.me/em-api/docs

النقاط الأساسية

نقاط النهاية الأكثر استخداماً:

الطريقةالمسارالوصولالوصف
GET/v1/seriesعامعرض والبحث في السلاسل المنشورة (الاسم، المعرف، الموضوع، المنطقة، الجهة، …)
GET/v1/series/{id}عامبيانات السلسلة بالمعرف
GET/v1/series/{id}/observationsمعاينة عامةملاحظات السلاسل الزمنية بصيغة JSON
GET/v1/series/{id}/observations.csvمفتاح APIتصدير الملاحظات بصيغة CSV
GET/v1/series/{id}/observations.xlsxمفتاح APIتصدير الملاحظات بصيغة Excel (.xlsx)
GET/v1/series/featuredعامسلاسل مميزة مختارة للصفحة الرئيسية
GET/v1/series/compareمعاينة عامةمحاذاة حتى 20 سلسلة على محور زمني مشترك
GET/v1/series/joinمفتاح APIاشتقاق نسبة لكل فرد أو مؤشر عابر للسلسلة من سلسلتين
GET/v1/series/rankingsعامترتيب السلاسل المنشورة حسب أحدث قيمة أو التغير خلال الفترة أو التغير السنوي
GET/v1/catalog/filtersعامفئات الكتالوج المتاحة (الموضوعات، الجهات، المناطق، أنواع القياس، …)
GET/v1/datasetsعاممجموعات البيانات المنشورة
GET/v1/datasets/{slug}/seriesعامالسلاسل التابعة لمجموعة بيانات
GET/v1/calendarعامتقويم الإصدارات القادمة
GET/v1/calendar.icsعامموجز تقويم الإصدارات القابل للاشتراك (ICS، iCalendar)
GET/v1/coverageعامإحصائيات تغطية مجموعات البيانات
GET/v1/source-agenciesعامقائمة الجهات المصدرة

صيغ البيانات

تُرجع الملاحظات بثلاث صيغ — اختر ما يناسب خط أنابيبك:

  • JSON — سجلات منظمة بالقيم والتكرارات والبيانات الوصفية
  • CSV — /observations.csv (تصدير جدولي مسطّح للجداول وخطوط ETL)
  • Excel — /observations.xlsx (مصنف Excel مع الحفاظ على التنسيق)

عوامل التصفية

يدمج GET /v1/series جميع عوامل التصفية باستخدام AND. يطابق البحث (q) اسم السلسلة الموضعي (جزء من النص) أو معرّف السلسلة (بادئة، مثل "SA.CPI").

المسارالوصف
qبحث حر: اسم السلسلة (جزء من النص) أو معرّف السلسلة (بادئة)
topicمعرّف الموضوع، مثل inflation
source_agencyالجهة المصدرة، مثل GASTAT
dataset_idمعرّف أو معرّف مختصر لمجموعة البيانات
measure_typeنوع القياس، مثل YoY
regionبُعد المنطقة، مثل national
classification_systemنظام التصنيف
source_publicationالمنشور المصدر
country_codeرمز الدولة (الافتراضي SA)
published_onlyالسلاسل المنشورة فقط (الافتراضي true)
localeلغة الاستجابة: en أو ar
limitحجم الصفحة، الافتراضي 50 والحد الأقصى 200
offsetإزاحة الترقيم، الافتراضي 0

المعاينة مقابل الكامل

تعيد الملاحظات السجل الكامل افتراضيًا. مرّر preview=true للحصول على نافذة محدودة للسلاسل المنشورة:

  • السلاسل الشهرية: آخر 12 شهرًا
  • السلاسل السنوية: آخر 5 سنوات
  • السلاسل اليومية/الأسبوعية: المعاينة غير متاحة (ترجع preview_blocked مع السبب granular)

تتطلب الملاحظات الكاملة أن تكون السلسلة منشورة؛ وعند تفعيل الاستحقاقات في البيئة، يلزم وجود خطة نشطة (Pro).

حدود المعدل

الحدود المكوّنة (لكل مستخدم أو عنوان IP؛ التطبيق قابل للتهيئة حسب البيئة):

  • الافتراضي: 100 طلب/دقيقة
  • النقاط العامة غير الموثقة: 30 طلب/دقيقة
  • تطبق حدود شهرية لطلبات API حسب الخطة — 3,000 طلب في تجربة Pro لمدة 7 أيام.

قد يُخفَّف التطبيق في بيئات التطوير؛ تفرض بيئة الإنتاج الحدود المكوّنة.

Webhooks

استقبل استدعاءات HTTP موقّعة عند نشر بيانات السلاسل أو تحديثها.

توثيق Webhooks →