تصفّح التوثيق كاملًا

مرجع API لسجل السكان

استرجع إجمالي السكان السنوي لدولة واحدة من البنك الدولي.

economics_get_population_history متاح عبر REST وعبر الأداة economics_get_population_history أداة MCP. كلتاهما تُرجع بنية البيانات نفسها وتستخدم الرصيد نفسه.

نقطة النهاية والطلب

نقطة نهاية REST
GET /v1/economics/{country}/population/observations
طلب نموذجي
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/population/observations?start=2024&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

يستخدم MCP أداة economics_get_population_history مع الوسيطات المقابلة أدناه.

المعلمات

تنسيق الفترة المقبول لهذه العملية هو YYYY.

الاسممطلوبالنوعالمعنى
countryنعمالمسار · ISO alpha-3رمز دولة واحد مدعوم بأحرف لاتينية كبيرة؛ راجع قائمة التغطية لهذه العملية.
startلاالاستعلام · YYYYأول فترة رصد، وهي مشمولة في النتائج.
endلاالاستعلام · YYYYآخر فترة رصد، وهي مشمولة في النتائج.
limitلاالاستعلام · عدد صحيح, 1–1000الحد الأقصى لعدد الفترات المُعادة. القيمة الافتراضية 100. قد تحتوي الصفحة على فترات أقل؛ اتبع next_cursor.
cursorلاالاستعلام · سلسلة نصية غير قابلة للتفسيرقيمة next_cursor من الصفحة السابقة.
versionلاالاستعلام · first_reportedيقبل `first_reported` فقط: يعيد أول قيمة مخزّنة لكل فترة مع `first_reported_at`. لا يمكن استخدامه مع `as_of`.
as_ofلاالاستعلام · YYYY-MM-DDيعيد السلسلة كما نُشرت حتى نهاية اليوم المحدد بتوقيت UTC. لا يمكن استخدامه مع `version`.

الاستجابة

استجابة نموذجية
{
  "country": "USA",
  "as_of": "2026-10-08T00:00:00Z",
  "source": {
    "publisher": "UN Population Division (World Population Prospects), national statistical offices, Eurostat, U.S. Census Bureau, Pacific Community: mid-year estimates",
    "distributor": "World Bank, World Development Indicators (CC BY 4.0)"
  },
  "unit": "person",
  "frequency": "annual",
  "observations": [
    {
      "period": "2024",
      "value": "340003797"
    },
    {
      "period": "2025",
      "value": "341784857"
    }
  ],
  "next_cursor": null
}
حقلالنوعمطلوبالمعنى
countryسلسلة نصيةنعمرمز البلد المطلوب بأحرف كبيرة وفق ISO alpha-3. يُعاد مرة واحدة لكل صفحة، وليس مع كل مشاهدة.
as_ofطابع زمني وفق RFC 3339لاوقت آخر تحديث أجراه المصدر لأحدث مشاهدة في هذه الصفحة، بدقة الثواني الكاملة، وفق UTC.
sourceكائننعميذكر publisher الجهات الناشرة الأصلية، ويذكر distributor مؤشرات التنمية العالمية للبنك الدولي (CC BY 4.0).
unitسلسلة نصيةنعمدائمًا person.
frequencyسلسلة نصيةنعمدائمًا annual.
observationsمصفوفةنعمالمشاهدات المعتمدة من الأقدم إلى الأحدث، مشاهدة واحدة لكل فترة. تُحذف قيم المصدر المفقودة ولا تُملأ أبدًا. قد تحتوي الصفحة على مشاهدات أقل من limit؛ اتبع next_cursor حتى تصبح قيمته null.
observations[].periodسلسلة نصيةنعمالشهر أو الربع أو السنة الرسمية التي تمثلها القراءة.
observations[].first_reported_atطابع زمني وفق RFC 3339لالا يظهر هذا الطابع الزمني بتوقيت UTC إلا مع version=first_reported، ويسجّل وقت تخزين Narwhal للفترة أول مرة (أحدث وقت إذا خُزّنت مقاييسها كلٌّ على حدة)؛ وتعرض الفترات التي نُشرت قبل بدء الالتقاط وقت أول التقاط لدى Narwhal.
observations[].valueسلسلة نصية لعدد عشرينعمعدد السكان في منتصف العام بالأشخاص كاملين. ويشمل جميع المقيمين بغض النظر عن وضعهم القانوني أو جنسيتهم. وقد تكون أحدث السنوات تقديرات مستقبلية.
next_cursorسلسلة نصية أو nullنعممرّر هذه القيمة دون تغيير في cursor لقراءة الصفحة التالية؛ وتكون null في الصفحة الأخيرة.

أخطاء API والرصيد

  • 400 invalid_query — تنسيق البلد أو الفترة أو عامل التصفية غير صالح، أو أُرسلت as_of وversion معًا.
  • 400 invalid_cursor — مؤشر ترقيم الصفحات غير صحيح الصيغة، أو صدر لمرشحات أخرى أو لعملية أخرى.
  • 401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
  • 404 series_not_found — لا توجد قراءة معتمدة تطابق الطلب.
  • 409 cursor_expired مؤشر ترقيم الصفحات قديم جدًا أو تغيرت البيانات التي يشير إليها. ابدأ مجددًا دون المؤشر.
  • 429 rate_limit_exceeded — تم بلوغ حد الشبكة أو الحساب خلال الفترة الزمنية القصيرة؛ أعد المحاولة بعد المدة المحددة في Retry-After.
  • 402 insufficient_credits — رصيدك لا يغطي الاستدعاء.
  • 503 economics_unavailable — لا يستطيع Narwhal تقديم إصدار مقبول بأمان.

Only a successful data response costs credit. راجع كل الأخطاء والترويسات وقواعد إعادة المحاولة.

حداثة البيانات

يعيد هذا المسار افتراضيًا السلسلة المعتمدة حاليًا لدى Narwhal؛ وتكون قيمة as_of في الاستجابة هي وقت تحديث أحدث رصد. يمكن لأي مفتاح قراءة نسخة تاريخية سابقة باستخدام as_of أو version=first_reported. يبدأ سجل النسخ التاريخية من أول التقاط لدى Narwhal، ولا يعيد بناء كل إصدار سابق.

قد تتضمن المصادر الرسمية قراءات متفرقة وتتيح بيانات تاريخية لفترات متفاوتة. ويحذف Narwhal القراءات المفقودة بدلًا من استيفائها أو ملئها بقيم سابقة.

اقرأ كيف تعمل فحوص المصدر والتحقق والإصدارات المخزنة والفحوص الفاشلة.

تغطية الإصدار التجريبي العام الحالي

215 الدول

ABW, AFG, AGO, ALB, AND, ARE, ARG, ARM, ASM, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BWA, CAF, CAN, CHE, CHL, CHN, CIV, CMR, COD, COG, COL, COM, CPV, CRI, CUB, CUW, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESP, EST, ETH, FIN, FJI, FRA, FRO, FSM, GAB, GBR, GEO, GHA, GIB, GIN, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUM, GUY, HKG, HND, HRV, HTI, HUN, IDN, IMN, IND, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, MYS, NAM, NCL, NER, NGA, NIC, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKM, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, USA, UZB, VCT, VEN, VGB, VIR, VNM, VUT, WSM, YEM, ZAF, ZMB, ZWE

يبدأ السجل السنوي في عام 1960، وفي عام 1990 بالنسبة إلى فلسطين. لا يوجد لكوسوفو وجزر القنال رمز ISO alpha-3، ولذلك لا تشملهما التغطية. لا يوجد مسار للقيمة الأحدث للسكان. يُحتسب كل طلب ناجح كطلب واحد من واجهة Economics.

مسارات Economics الإندونيسية والإقليمية ليست عامة. يتوفر FX اليومي عبر واجهة API لأسعار الصرف.

العودة إلى جميع عمليات Economics.

هل كانت هذه الصفحة مفيدة؟