مرجع الواجهة البرمجية

الأخبار والأسواق

عناوين أخبار حيّة وأسعار أسواق، تُجلَب من جهة الخادم فلا يتّصل عميلك بأي تغذية من طرف ثالث.

الأخبار والأسواق

نقطتا نهاية صغيرتان للقراءة فقط تغذّيان الأدوات المحيطة في شاشة Navvo الرئيسية أو شاشة الخريطة: تغذية أخبار مُرشَّحة حسب الموضوع واستعلام عن أسعار الأسواق. تُجلَب كلتاهما وتُخزَّن مؤقّتاً من جهة الخادم، فيُجري عميلك طلباً واحداً إلى Navvo من المصدر نفسه بدلاً من الاتصال بتغذية من طرف ثالث لها مفاتيحها وحصصها وقيود CORS الخاصة بها.

النطاق المطلوب: لا شيء — يكفي أي مفتاح API صالح.

وُجدت هاتان النقطتان لملء أداة عرض، لا لتكونا منصّة أخبار أو بيانات مالية. والاستجابات قصيرة ومخزَّنة مؤقّتاً وسطحية عن قصد: عنوان ورابط وصورة وطابع زمني للأخبار؛ وآخر سعر وتغيّر اليوم للأسواق. وإن احتجت مقالات كاملة أو بيانات تاريخية أو تحرّكات لحظية، فاستخدم مزوّداً متخصّصاً.

GET /widgets/news

أحدث العناوين عبر موضوع واحد أو أكثر، متداخلةً بحيث يكون كل موضوع طلبته مُمثَّلاً.

curl -s "https://navvo.io/api/v1/widgets/news?topics=business,technology&limit=10" \
  -H "x-api-key: nvvo_YOUR_KEY"

معاملات الاستعلام

topics

string

قائمة مواضيع مفصولة بفواصل. المدعوم: world وmiddleeast وbusiness وtechnology وscience وhealth وsports. وتُهمَل المواضيع غير المعروفة بصمت؛ فإن لم يبقَ شيء صالح، يعود إلى world. القيمة الافتراضية world.

limit

integer

أقصى عدد عناوين يُعاد، من 1 إلى 20. القيمة الافتراضية 8. وتُقصّ القيم خارج المدى إلى حدوده.

الاستجابة

{
  "ok": true,
  "topics": ["business", "technology"],
  "items": [
    {
      "title": "Is football AI-proof? Why tech investors wanted a slice of the World Cup",
      "url": "https://www.bbc.co.uk/news/articles/cd7l4e3v238o",
      "source": "BBC Business",
      "image": "https://ichef.bbci.co.uk/ace/standard/240/cpsprodpb/…jpg",
      "topic": "business",
      "publishedAt": "2026-08-09T08:12:00.000Z"
    }
  ]
}

boolean

تكون false عندما يتعذّر تجميع أي عنوان إطلاقاً (تعذّر الوصول إلى كل التغذيات الأعلى). وتكون items عندئذٍ فارغة — اعرض حالة الفراغ في أداتك بدل معاملة ذلك كخطأ؛ فحالة HTTP تبقى 200.

topics

string[]

المواضيع المستخدَمة فعلياً بعد إسقاط غير المعروف منها. قارِنها بما أرسلته لاكتشاف أي خطأ إملائي.

items[].source

string

الجهة الناشرة التي جاء منها العنوان. اعرِضها — فأنت تُبرز عملاً صحفياً لجهة أخرى، وينبغي أن يشير الرابط إلى صفحتها.

items[].image

string | null

رابط صورة مصغّرة عندما توفّرها التغذية، وإلا null. تحقّق دائماً من null.

items[].publishedAt

string | null

طابع زمني ISO-8601 بتوقيت UTC، أو null عندما تُغفل التغذية التاريخ.

التداخل. تُدمَج المواضيع بالتناوب الدوري لا بالتسلسل — فطلب business,technology مع limit=10 يعطيك نحو خمسة من كل منهما بترتيب متناوب، لا عشرة عناوين أعمال. اطلب موضوعاً واحداً إن أردت قائمة بموضوع واحد.

التخزين المؤقّت. يُخزَّن كل موضوع مؤقّتاً لمدة 10 دقائق من جهة الخادم. والاستطلاع بوتيرة أسرع من ذلك يعيد الحمولة نفسها ويستهلك حصّتك بلا فائدة — حدِّث كل 10 دقائق أو عند تركيز الشاشة.

GET /widgets/markets

آخر سعر وتغيّر اليوم لاثني عشر رمزاً كحدٍّ أقصى.

curl -s "https://navvo.io/api/v1/widgets/markets?symbols=AAPL,MSFT" \
  -H "x-api-key: nvvo_YOUR_KEY"

معاملات الاستعلام

symbols

string

قائمة رموز تداول مفصولة بفواصل، بحدٍّ أقصى 12 (ويُهمَل ما زاد). تستخدم الأسهم رمزها المجرّد (AAPL وMSFT)، وتستخدم الأزواج الصيغة الموصولة بشَرطة (BTC-USD). القيمة الافتراضية AAPL,MSFT,GOOGL,BTC-USD.

الاستجابة

{
  "ok": true,
  "items": [
    { "symbol": "AAPL", "name": "Apple",     "price": 313.33, "currency": "USD", "change": 2.33,  "changePct": 0.75 },
    { "symbol": "MSFT", "name": "Microsoft", "price": 499.99, "currency": "USD", "change": 12.53, "changePct": 2.57 }
  ]
}

boolean

تكون true عندما يُحَل رمز واحد على الأقل إلى سعر. ووجود رمز واحد غير معروف لا يُفشل الطلب.

items[].name

string

اسم مألوف للرموز المعروفة، ويعود إلى الرمز نفسه عندما يكون غير معروف.

items[].price

number | null

آخر سعر تداول، أو null إن تعذّر حلّ الرمز. تحقّق من null قبل التنسيق — فالرمز غير المعروف يعيد مُدخَلاً على أي حال كي تتطابق الاستجابة مع ما طلبته.

items[].change / changePct

number | null

التغيّر المطلق والنسبي خلال اليوم. والقيم السالبة تعني أن الرمز منخفض.

التخزين المؤقّت. تُخزَّن الأسعار مؤقّتاً لمدة 60 ثانية لكل رمز. هذه تغذية لأداة عرض لا شريط تداول — فلا تبنِ شيئاً يعتمد على حداثة لحظية.

الأخطاء

تعيد النقطتان 200 مع ok: false ومصفوفة items فارغة عندما تكون بياناتهما الأعلى غير متاحة، بدلاً من إظهار إخفاق الجهة الأعلى بوصفه 5xx. صمِّم أداتك لحالة الفراغ. وتنطبق أخطاء المصادقة وحدود المعدّل المعتادة كالمألوف.

الملاحة

مستوى التحكّم في الملاحة اللحظية منعطفاً بمنعطف — جلسات مُدارة، وتقدّم وخروج عن المسار محسوبان من الخادم، وزمن وصول متوقّع حيّ، واكتشاف الوصول، وسجل أحداث، ونص إرشاد منطوق.

اقتراحات البحث

اقتراحات الإكمال التلقائي لمربّع البحث — أسماء تصنيفات وأماكن ومناطق من مفردات Navvo الخاصة، إضافةً إلى عبارات بحث راجعها فريق Navvo.