واجهة API للبحث عن الشركات

ابحث عن مُصدر SEC مشمول بالاسم أو Ticker أو CIK ذي العشرة أرقام.

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

متاح باستخدام مفتاح Narwhal API.

نقطة نهاية REST

GET /v1/companies

طلب

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies?query=AAPL&limit=20" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

المعلمات

الاسم	مطلوب	النوع	المعنى
`query`	نعم	الاستعلام · سلسلة نصية من 1 إلى 200 محرف	اسم الشركة أو Ticker أو CIK المكوّن من عشرة أرقام. المطابقة بالاسم وTicker غير حساسة لحالة الأحرف.
`limit`	لا	الاستعلام · عدد صحيح, 1–100	الحد الأقصى للشركات المعادة. الافتراضي 20.
`cursor`	لا	الاستعلام · سلسلة نصية غير قابلة للتفسير	رمز المتابعة من الصفحة السابقة. وهو مرتبط بالاستعلام والمرشحات الأصلية.

الاستجابة

{
  "query": "AAPL",
  "companies": [
    {
      "id": "cmp_a1b2c3d4e5f678901234567890abcdef",
      "name": "Apple Inc.",
      "cik": "0000320193",
      "listings": [
        {
          "ticker": "AAPL",
          "exchange": "Nasdaq"
        }
      ]
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T12:00:00Z"
}

حقل	النوع	مطلوب	المعنى
`query`	سلسلة نصية	نعم	نص البحث الموحّد.
`companies`	مصفوفة	نعم	هويات شركات ثابتة مع CIK وأسماء الإدراج الحالية البديلة.
`next_cursor`	سلسلة نصية أو قيمة فارغة	نعم	رمز متابعة غير شفاف، أو قيمة فارغة عند اكتمال الصفحة.
`as_of`	طابع وقت UTC	نعم	وقت اللقطة المشترك بين كل نتيجة في الصفحة.

الأخطاء والحصة

400 invalid_query — الاستعلام أو التاريخ أو الاستمارة أو الحد أو المؤشر غير صالح.
401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
429 rate_limit_exceeded أو quota_exhausted — استُنفدت الحصة القصيرة أو الشهرية المشتركة.
503 companies_unavailable — Companies معطّلة، أو الحقوق غير نشطة، أو لا يمكن تقديم إصدار كامل مقبول.

لا تستهلك إخفاقات المصادقة والطلبات المرفوضة بسبب التقييد الحصة الشهرية. وتستخدم استدعاءات REST وMCP الناجحة مخصص الحساب نفسه.

نطاق الإصدار الأول

تُستمد مجموعة الإطلاق من لقطة معتمدة لارتباط رموز التداول بمعرّفات CIK لدى SEC. رمز التداول المُعاد اسم بديل، وليس دليلًا على إدراج نشط.

تقتصر التغطية على مجموعة المُصدرين المقبولة. اقرأ وقت as_of في الاستجابة وصفحة التغطية لمعرفة اللقطة المتاحة.