مرجع API لسجل السكان
استرجع إجمالي السكان السنوي لدولة واحدة من البنك الدولي.
economics_ متاح عبر REST وعبر الأداة economics_ أداة MCP. كلتاهما تُرجع بنية البيانات نفسها وتستخدم الرصيد نفسه.
نقطة النهاية والطلب
GET /v1/economics/{country}/population/observationscurl --request GET \
--url "https://api.narwhalapi.com/v1/economics/USA/population/observations?start=2024&limit=100" \
--header "Authorization: Bearer $NARWHAL_API_KEY"يستخدم MCP أداة economics_ مع الوسيطات المقابلة أدناه.
المعلمات
تنسيق الفترة المقبول لهذه العملية هو 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_ | لا | الاستعلام · 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_ | طابع زمني وفق RFC 3339 | لا | وقت آخر تحديث أجراه المصدر لأحدث مشاهدة في هذه الصفحة، بدقة الثواني الكاملة، وفق UTC. |
source | كائن | نعم | يذكر publisher الجهات الناشرة الأصلية، ويذكر distributor مؤشرات التنمية العالمية للبنك الدولي (CC BY 4.0). |
unit | سلسلة نصية | نعم | دائمًا person. |
frequency | سلسلة نصية | نعم | دائمًا annual. |
observations | مصفوفة | نعم | المشاهدات المعتمدة من الأقدم إلى الأحدث، مشاهدة واحدة لكل فترة. تُحذف قيم المصدر المفقودة ولا تُملأ أبدًا. قد تحتوي الصفحة على مشاهدات أقل من limit؛ اتبع next_cursor حتى تصبح قيمته null. |
observations[].period | سلسلة نصية | نعم | الشهر أو الربع أو السنة الرسمية التي تمثلها القراءة. |
observations[].first_ | طابع زمني وفق RFC 3339 | لا | لا يظهر هذا الطابع الزمني بتوقيت UTC إلا مع version=first_، ويسجّل وقت تخزين Narwhal للفترة أول مرة (أحدث وقت إذا خُزّنت مقاييسها كلٌّ على حدة)؛ وتعرض الفترات التي نُشرت قبل بدء الالتقاط وقت أول التقاط لدى Narwhal. |
observations[].value | سلسلة نصية لعدد عشري | نعم | عدد السكان في منتصف العام بالأشخاص كاملين. ويشمل جميع المقيمين بغض النظر عن وضعهم القانوني أو جنسيتهم. وقد تكون أحدث السنوات تقديرات مستقبلية. |
next_ | سلسلة نصية أو null | نعم | مرّر هذه القيمة دون تغيير في cursor لقراءة الصفحة التالية؛ وتكون null في الصفحة الأخيرة. |
أخطاء API والرصيد
400 invalid_— تنسيق البلد أو الفترة أو عامل التصفية غير صالح، أو أُرسلتquery as_وof versionمعًا.400 invalid_— مؤشر ترقيم الصفحات غير صحيح الصيغة، أو صدر لمرشحات أخرى أو لعملية أخرى.cursor 401 invalid_— مفتاح Bearer مفقود أو مرفوض.api_ key 404 series_— لا توجد قراءة معتمدة تطابق الطلب.not_ found 409 cursor_مؤشر ترقيم الصفحات قديم جدًا أو تغيرت البيانات التي يشير إليها. ابدأ مجددًا دون المؤشر.expired 429 rate_— تم بلوغ حد الشبكة أو الحساب خلال الفترة الزمنية القصيرة؛ أعد المحاولة بعد المدة المحددة فيlimit_ exceeded Retry-After.402 insufficient_— رصيدك لا يغطي الاستدعاء.credits 503 economics_— لا يستطيع Narwhal تقديم إصدار مقبول بأمان.unavailable
Only a successful data response costs credit. راجع كل الأخطاء والترويسات وقواعد إعادة المحاولة.
حداثة البيانات
يعيد هذا المسار افتراضيًا السلسلة المعتمدة حاليًا لدى Narwhal؛ وتكون قيمة as_ في الاستجابة هي وقت تحديث أحدث رصد. يمكن لأي مفتاح قراءة نسخة تاريخية سابقة باستخدام as_ أو version=first_. يبدأ سجل النسخ التاريخية من أول التقاط لدى 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.
ابدأ بمفتاح مجاني
رصيد مجاني بقيمة 10 دولارات كل شهر، دون بطاقة.رصيد مجاني بقيمة 10 دولارات كل شهر، دون بطاقة.
هل كانت هذه الصفحة مفيدة؟