نظرة عامة

دليل شامل للبحث عن شعارات الشركات والصناديق والعملات المشفّرة واسترجاعها باستخدام معرّفات متعددة

​

المقدمة

توفر واجهة برمجة التطبيقات API لشعارات Benzinga إمكانية الوصول إلى شعارات عالية الجودة للشركات والصناديق والعملات المشفّرة. يمكنك البحث عن الشعارات باستخدام عدة أنواع من المعرّفات بما في ذلك الرموز، وأرقام CIK، وأكواد رقم التعريف الدولي للأوراق المالية ISIN، وCUSIP، وFIGI، وغيرها.

​

نقاط النهاية المتاحة

​

/logos/search

يتيح البحث عن الشعارات باستخدام معرّفات مختلفة. يُرجع عناوين URL للشعارات، وتفاصيل الأوراق المالية، والبيانات الوصفية.

​

/logos/sync

واجهة مزامنة جماعية لاسترجاع شعارات متعددة مع دعم تقسيم النتائج إلى صفحات (pagination).

​

عوامل البحث

تتيح واجهة برمجة التطبيقات API بحثًا مرنًا من خلال معاملين رئيسيين:

• search_keys - قيمة المعرّف الذي تريد البحث باستخدامه
• search_keys_type - نوع المعرّف (اختياري؛ القيمة الافتراضية symbol)

​

1. التصفية حسب الرمز

ابحث عن الشعارات باستخدام رموز تداول الأسهم.

المعلمات:

• search_keys: رمز التداول (على سبيل المثال: AAPL, TSLA, MSFT)
• search_keys_type: symbol (اختياري، وهو الإعداد الافتراضي)

مثال:

GET /api/v2/logos/search?search_keys=AAPL&search_keys_type=symbol&fields=logo_light,logo_dark

​

2. التصفية حسب CIK

ابحث باستخدام مفتاح الفهرس المركزي (Central Index Key) الخاص بـ SEC. يدعم القيم ذات الأصفار البادئة ومن دونها.

المعاملات:

• search_keys: رقم CIK (مثلًا: 320193 أو 0000320193)
• search_keys_type: cik

مثال:

GET /api/v2/logos/search?search_keys=320193&search_keys_type=cik&fields=logo_light,logo_dark

مثال على CIK بأصفار بادئة:

GET /api/v2/logos/search?search_keys=0000320193&search_keys_type=cik&fields=logo_light,logo_dark

​

3. التصفية حسب رقم التعريف الدولي للأوراق المالية ISIN

ابحث باستخدام رقم التعريف الدولي للأوراق المالية ISIN.

المعاملات:

• search_keys: رمز رقم التعريف الدولي للأوراق المالية ISIN (مثال: US0378331005)
• search_keys_type: isin

مثال:

GET /api/v2/logos/search?search_keys=US0378331005&search_keys_type=isin&fields=logo_light,logo_dark

​

4. التصفية حسب فئة أسهم FIGI

ابحث باستخدام معرّف Bloomberg العالمي للأداة المالية (Financial Instrument Global Identifier) لفئات الأسهم.

المعاملات:

• search_keys: معرّف فئة أسهم FIGI (مثلًا: BBG001SQKGD7)
• search_keys_type: figi_share_class

مثال:

GET /api/v2/logos/search?search_keys=BBG001SQKGD7&search_keys_type=figi_share_class&fields=logo_light,logo_dark

​

5. التصفية حسب CUSIP

ابحث باستخدام رقم CUSIP (اختصارًا لـ Committee on Uniform Securities Identification Procedures).

المعاملات:

• search_keys: رقم CUSIP (مثلًا، 88160R101)
• search_keys_type: cusip

مثال:

GET /api/v2/logos/search?search_keys=88160R101&search_keys_type=cusip&fields=logo_light,logo_dark

​

6. التصفية حسب الرمز مع العملة والبلد

قيِّد الرموز برموز الدولة أو العملة باستخدام النقطتين (:) أو النقطة (.) كفاصل.

المعاملات:

• search_keys: الرمز مع المحدِّد (مثلًا، AAPL:US، AAPL:USD، AAPL.US)
• search_keys_type: symbol

أمثلة:

GET /api/v2/logos/search?search_keys=AAPL:US&search_keys_type=symbol&fields=logo_light,logo_dark
GET /api/v2/logos/search?search_keys=AAPL:USD&search_keys_type=symbol&fields=logo_light,logo_dark
GET /api/v2/logos/search?search_keys=AAPL.US&search_keys_type=symbol&fields=logo_light,logo_dark

​

7. التصفية حسب الـ Exchange والرمز

ابحث عن طريق الجمع بين رمز الـ exchange والرمز. يدعم كلًا من تنسيق Bloomberg-style (قديم) وتنسيق LSEG-style.

مطابقة بأسلوب Bloomberg-style (قديم):

• search_keys: الـ exchange والرمز (مثلًا NASDAQ:AAPL)
• search_keys_type: symbol

رمز LSEG المكوَّن من 3 أحرف (الحالي):

• search_keys: رمز الـ exchange والرمز (مثلًا NSQ:AAPL)
• search_keys_type: symbol

أمثلة:

GET /api/v2/logos/search?search_keys=NASDAQ:AAPL&search_keys_type=symbol&fields=logo_light,logo_dark
GET /api/v2/logos/search?search_keys=NSQ:AAPL&search_keys_type=symbol&fields=logo_light,logo_dark

​

8. التصفية حسب رمز ISO MIC والرمز

ابحث باستخدام رمز معرّف السوق وفق معيار ISO (ISO Market Identifier Code - MIC) مع الرمز (symbol).

المعاملات:

• search_keys: رمز MIC والرمز (مثلًا: XYNS:AAPL)
• search_keys_type: symbol

مثال:

GET /api/v2/logos/search?search_keys=XYNS:AAPL&search_keys_type=symbol&fields=logo_light,logo_dark

​

9. مرشحات شعارات العملات الرقمية

ابحث عن شعارات العملات الرقمية باستخدام تنسيقات متعددة. تتعرّف واجهة برمجة التطبيقات API تلقائيًا على تنسيقات العملات الرقمية حتى في حال عدم تحديد search_keys_type.

التنسيقات المدعومة:

• CRYPTO:BTC
• CRYPTO/BTC
• $BTC
• BTC/USD

أمثلة:

GET /api/v2/logos/search?search_keys=CRYPTO:BTC&fields=logo_light,logo_dark
GET /api/v2/logos/search?search_keys=CRYPTO/BTC&fields=logo_light,logo_dark
GET /api/v2/logos/search?search_keys=$BTC&fields=logo_light,logo_dark
GET /api/v2/logos/search?search_keys=BTC/USD&fields=logo_light,logo_dark

​

الحقول المتاحة

يمكنك طلب أنواع شعارات محددة باستخدام معلمة fields. تتضمن الحقول المتاحة ما يلي:

• logo_light - شعار لسمة واجهة فاتحة (PNG)
• logo_dark - شعار لسمة واجهة داكنة (PNG)
• logo_vector_light - شعار متجهي لسمة واجهة فاتحة (SVG)
• logo_vector_dark - شعار متجهي لسمة واجهة داكنة (SVG)
• mark_light - علامة/أيقونة لسمة واجهة فاتحة (PNG)
• mark_dark - علامة/أيقونة لسمة واجهة داكنة (PNG)
• mark_vector_light - علامة/أيقونة متجهية لسمة واجهة فاتحة (SVG)
• mark_vector_dark - علامة/أيقونة متجهية لسمة واجهة داكنة (SVG)
• mark_composite_light - علامة مركّبة لسمة واجهة فاتحة (PNG)
• mark_composite_dark - علامة مركّبة لسمة واجهة داكنة (PNG)
• mark_vector_composite_light - علامة مركّبة متجهية لسمة واجهة فاتحة (SVG)
• mark_vector_composite_dark - علامة مركّبة متجهية لسمة واجهة داكنة (SVG)

مثال على طلب عدة حقول:

GET /api/v2/logos/search?search_keys=TSLA&fields=logo_light,logo_dark,mark_vector_composite_light

​

معلمات إضافية

​

تخصيص الصورة

• scale - تغيير مقياس الصورة (مثلًا: 100x100, 300x300)
• max_width - أقصى عرض للصورة المُرجَعة
• composite_radius - نصف قطر الزوايا للصور المركّبة (عدد صحيح، النطاق 0-50)
• composite_auto - إنشاء الصور المركّبة تلقائيًا (قيمة منطقية)

​

ترقيم الصفحات (للمزامنة المجمّعة فقط)

• page - رقم الصفحة (عدد صحيح)
• pagesize - عدد النتائج لكل صفحة (عدد صحيح)
• updated_since - التصفية حسب الطابع الزمني لآخر تحديث (صيغة ISO 8601)

​

تفاصيل الأوراق المالية

• securities - تضمين معلومات تفصيلية عن الأوراق المالية في الاستجابة (boolean)

​

أمثلة على الاستجابات

​

استجابة 200 ناجحة

{
  "ok": true,
  "data": [
    {
      "id": "efc3943a-ddac-4f59-a2cc-47a67583068b",
      "search_key": "TSLA",
      "securities": [
        {
          "symbol": "TSLA",
          "name": "TESLA INC",
          "cik": "1318605",
          "exchange": "NASDAQ",
          "mic_code": "XNAS",
          "exchange_name": "NASDAQ Global Select Consolidated",
          "cusip": "88160R101",
          "isin": "US88160R1014",
          "country": "US",
          "figi_share_class": "BBG001SQKGD7",
          "figi": "BBG000N9MNX3",
          "security_type": "Common Stock"
        }
      ],
      "files": {
        "logo_dark": "https://image-util.benzinga.com/api/v2/logos/file/image/1318605/logo_dark__53646042d4c8b507c7eddb70110ee334.png?x-bz-cred=...",
        "logo_light": "https://image-util.benzinga.com/api/v2/logos/file/image/1318605/logo_light__6895726d0ff148e46c238f91d033e72a.png?x-bz-cred=..."
      },
      "created_at": "2022-05-18T05:19:45.008547Z",
      "updated_at": "2025-02-05T09:43:14.303261Z"
    }
  ]
}

​

استجابة 401 غير المصرح بها

{
  "ok": false,
  "errors": [
    {
      "code": "auth_failed",
      "id": "unauthorized",
      "value": "رمز وصول غير صالح أو مفقود"
    }
  ]
}

​

استجابة 404 لم يتم العثور عليها

{
  "ok": false,
  "errors": [
    {
      "code": "no_data_found",
      "id": "not_found",
      "value": "No logos found for the specified search key"
    }
  ]
}

​

استجابة خطأ 500 للخادم الداخلي

{
  "ok": false,
  "errors": [
    {
      "code": "internal_server_error",
      "id": "server_error",
      "value": "حدث خطأ غير متوقع أثناء معالجة الطلب"
    }
  ]
}

​

المصادقة

تتطلب جميع نقاط نهاية Logos API إجراء مصادقة باستخدام مفتاح واجهة برمجة التطبيقات API. تضمين رمز الوصول الخاص بك كمعامل في سلسلة الاستعلام:

?token=YOUR_API_KEY

​

أفضل الممارسات

1. حدد search_keys_type - رغم أن واجهة برمجة التطبيقات API تستخدم افتراضيًا القيمة symbol، فإن تحديد النوع صراحةً يحسّن الوضوح والأداء
2. اطلب الحقول المطلوبة فقط - اطلب فقط أنواع الشعارات التي تحتاجها لتقليل حجم الاستجابة وتحسين الأداء
3. استخدم bulk-sync لمجموعات البيانات الكبيرة - عند جلب عدة شعارات، استخدم نقطة النهاية /logos/bulk-sync مع الترقيم الصفحي (pagination)
4. خزّن الاستجابات مؤقتًا - عناوين url الخاصة بالشعارات تتضمن طوابع زمنية لانتهاء الصلاحية؛ خزّنها مؤقتًا بشكل مناسب لتقليل عدد استدعاءات واجهة برمجة التطبيقات API
5. تعامل مع الأخطاء بسلاسة - تحقَّق دائمًا من الحقل ok في الاستجابات وتعامل مع حالات الخطأ بالشكل المناسب

​

حدود المعدل

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

​

الدعم

للحصول على مساعدة إضافية أو لطرح أسئلة حول Logos API، تواصل مع دعم واجهة برمجة التطبيقات لدى Benzinga أو راجع التوثيق التفصيلي لنقاط النهاية.