مرجع حقول التوسع

هذا هو قاموس الحقول لواجهة Expansion API: ما تفعله كل مرشح طلب وما يعنيه كل حقل استجابة. لمعرفة سبب بناء النموذج على هذا النحو، راجع كيف تعمل إشارات التوسع وكتالوج القيم في كيف تعمل إشارات التوسع. للحصول على قائمة محدَّثة دائمًا بالقيم المسموح بها، استدعِ نقطة تصنيف التوسع.

الأبعاد الأساسية

يُوصف كل توسع على طول محاور مستقلة قليلة. لا تخلط بينها:

الحقل	ما يلتقطه	قيم نموذجية
`stage`	مدى تقدم الشركة في سوق ما	`exploring`، `committing`، `expanding`، `scaling`
`presence.level`	مدى استقرار بصمة الشركة بالفعل، بمعزل عن المرحلة	`established`، `emerging`، `none`، `no_data`
`momentum`	مسار التحرك الحالي	`advancing`، `steady`، `pulling_back`
التدفق (flow)	اتجاه التحرك بين الأسواق، معبَّرًا عنه بـ `froms` / `tos`	صادر (`froms`)، وارد (`tos`)، ممر (`froms`→`tos`)
`freshness`	مدى حداثة الأدلة	`fresh`، `cooling`، `stale`، `cold`
`scope`	ما إذا كان سوقًا جديدة أو نموًا ضمن حضور قائم	`entering_new_market`، `expanding_within_presence`، `established_only`
`expansion_score`	تصنيف قابل للترتيب من 0 إلى 1 لمدى أهمية التوسع	`0.72`

أسماء المراحل القياسية هي exploring وcommitting وexpanding وscaling — استكشاف، التزام، توسع، تنمية. أما established فهي ليست مرحلة؛ بل هي presence.level، لذا فإن تصفية stages: ["established"] لا تطابق شيئًا وتُعيد نتائج غير مصفّاة بصمت.

التدفق (اتجاه التحرك) وmomentum (المسار) أمران مختلفان. التصفية حسب “الشركات المتقدمة” تكون بـ momentum: ["advancing"]؛ والتصفية حسب “الشركات المتوسعة إلى الولايات المتحدة” تكون بـ tos: ["US"]. لا يوجد حقل طلب منفصل باسم direction — يُحدَّد التدفق بالكامل بواسطة froms / tos.

مرشحات الطلب

الأسواق (`froms` / `tos`)

الجغرافيا علاقة موجَّهة: تتوسع الشركات من منشأ إلى هدف. تعبّر قائمتان عن كل حالة — دون علَم اتجاه منفصل.

المعامل	النوع	المعنى
`froms`	`string[]` (ISO حرفين)	أسواق المنشأ — من أين تتوسع الشركة (موطنها/مقرها).
`tos`	`string[]` (ISO حرفين)	الأسواق المستهدفة — إلى أين تتوسع الشركة.
`exclude_froms`	`string[]` (ISO حرفين)	أسواق المنشأ المستبعدة.
`exclude_tos`	`string[]` (ISO حرفين)	الأسواق المستهدفة المستبعدة.

ما ترسله	ما تحصل عليه
`tos: ["US"]`	كل من يتوسع إلى الولايات المتحدة (وارد).
`froms: ["CN"]`	الشركات الصينية المتوسعة إلى أي مكان (صادر).
`froms: ["CN"]`، `tos: ["US"]`	ممر CN → US فقط.
لا هذا ولا ذاك	كل التوسعات، عالميًا.

مرشحات إشارات التوسع

المعامل	النوع	المعنى
`stages`	`string[]`	التحديد لمرحلة توسع واحدة أو أكثر.
`momentum`	`string[]`	التحديد حسب المسار (`advancing`/`steady`/`pulling_back`).
`freshness`	`string[]`	التحديد حسب حداثة الأدلة (`fresh`/`cooling`/`stale`/`cold`).
`scopes`	`string[]`	التحديد حسب `entering_new_market` / `expanding_within_presence` / `established_only`.
`signal_types`	`string[]`	التحديد لأنواع إشارات محددة (`HIRE`، `OFFICE`، `AD`، `NEWS`، `DNS`، …).
`signal_strengths`	`string[]`	التحديد حسب فئة ثقة الأدلة: `low` أو `medium` أو `high`. (مختلف عن `signal_strength_slug` الخاص بكل إشارة، والذي يمتد حتى `very_high`.)
`min_signal_count`	`integer`	الحد الأدنى لعدد إشارات التوسع — يُظهر المتحركين ذوي البصمة الثقيلة.
`ahead_of_pace`	`boolean`	الشركات المتحركة أسرع من وتيرة ذلك السوق المعتادة فقط.
`only_contraction`	`boolean`	الأسواق المعرَّضة للخطر/المتقلصة فقط.
`min_markets`	`integer`	الحد الأدنى لعدد الأسواق الجديدة المميزة التي دخلتها شركة ضمن النافذة.

البيانات الوصفية للشركة

المعامل	النوع	المعنى
`verticals`، `technologies`	`string[]`	مرشحات صناعة الشركة/حزمة التقنيات.
`employees`	`number[][]`	نطاقات عدد الموظفين، مثل `[[50, 200]]`.
`founded_dates`	`number[]`	نطاق سنة التأسيس `[from, to]`.
`revenues`	`number[]`	نطاق الإيرادات بالدولار الأمريكي `[from, to]`.
`keywords`	`string[]`	تحديد نطاق موضوعي بنص حر.
`companies`	`string[]`	التحديد لشركات محددة عبر أي مزيج من `domain_search_id` أو النطاق أو رابط LinkedIn (تُحلّ النطاقات/الروابط إلى أفضل شركة مطابقة مرتبة).

النافذة الزمنية والبحث

المعامل	النوع	المعنى
`transitioned_dates`	`string[]`	نافذة الإشارة/الانتقال كنطاق ISO بصيغة `[from, to]`.
`window_days`	`integer`	نافذة متحركة بالأيام، تُستخدم عند عدم توفير `transitioned_dates`.
`query`	`string`	بحث باللغة الطبيعية — يفسّره Pubrio إلى مرشحات (يُعرَض في `filters`).
`is_explain_match`	`boolean`	أضِف `match_summary` بذكاء اصطناعي لكل شركة، مستند إلى إشاراتها الحقيقية. يتناسب عدد الإشارات المُستشهَد بها وحجم الدفعة مع `per_page`؛ تُلخَّص المصادر عالية الحجم (إعلانات الوظائف، الحملات الإعلانية) كعدد بدلًا من سردها فرديًا.
`sort_by`	`string`	ترتيب النتائج: `recent` أو `expansion_score` أو `signal_count` أو `company_ranking`. اتركه فارغًا لترتيب الصلة الافتراضي — الأزواج المدعَّمة (نوعا إشارة مميزان أو أكثر) أولًا، ثم أزواج الأدلة المتكررة (3 إشارات أو أكثر)، الأحدث أولًا ضمن كل مستوى. استخدم `recent` للحداثة الصرفة.

حقول الاستجابة

`stage` لكل شركة/سوق

الحقل	المعنى
`stage.slug`	المرحلة الحالية (`exploring` … `scaling`).
`stage.expansion_score`	تصنيف أهمية قابل للترتيب من 0 إلى 1.
`stage.scope`	سوق جديدة مقابل ضمن حضور قائم.
`stage.direction`	مسار المرحلة: `advancing` أو `steady` أو `retreating` أو `new`. هذا هو عرض جانب الاستجابة لنفس محور المسار الذي تصفّي عليه بمعامل الطلب `momentum` — يستخدم الاثنان مجموعتي قيم مختلفتين، لذا طابق وفقًا لذلك.
`stage.freshness`	فئة حداثة أحدث دليل.
`stage.signal_count`	عدد إشارات التوسع النشطة في هذا السوق.
`stage.first_signal_at` / `latest_signal_at` / `last_transition_at`	الطوابع الزمنية الأساسية.

الإشارات والحضور والتفسير

الحقل	المعنى
`signals[]`	الأدلة الأساسية: `signal_type`، `signal_subtype`، `signal_strength`، `polarity`، `event_date`، `source_type`، `display_label`، `evidence_url`.
`presence[]`	البصمة السوقية المعروفة (مكاتب/كيانات): `presence_type`، `presence_strength`، `address`، `known_since`.
`timeline[]`	سجل انتقالات المرحلة: `stage_slug`، `transitioned_at`، `transition_kind`.
`other_markets[]`	الأسواق النشطة الأخرى للشركة، كل منها بمرحلته وعدداته.
`match_summary`	(عند `is_explain_match: true`) `{ text, citations }` — “سبب المطابقة” بذكاء اصطناعي، مستشهَد بإشارات الشركة الحقيقية. يحمل كل استشهاد حقل `count`: `null` لإشارة فردية حقيقية، أو عدد صحيح عندما يكون الاستشهاد عد حجم محدَّد بنافذة (إعلانات الوظائف، الحملات الإعلانية) بدلًا من حدث واحد.

expansion_score هو تصنيف قابل للترتيب (قابل للمقارنة عبر الشركات). وهو مختلف عن ثقة النموذج، والتي تتضمنها استجابات مفتاح API فقط عند ضبط is_include_metadata: true.

قاعدة المعرفة

الأدلة

المفاهيم

دراسات الحالة

الأبعاد الأساسية

مرشحات الطلب

الأسواق (`froms` / `tos`)

مرشحات إشارات التوسع

البيانات الوصفية للشركة

النافذة الزمنية والبحث

حقول الاستجابة

`stage` لكل شركة/سوق

الإشارات والحضور والتفسير

​الأبعاد الأساسية

​مرشحات الطلب

​الأسواق (froms / tos)

​مرشحات إشارات التوسع

​البيانات الوصفية للشركة

​النافذة الزمنية والبحث

​حقول الاستجابة

​stage لكل شركة/سوق

​الإشارات والحضور والتفسير

الأبعاد الأساسية

مرشحات الطلب

الأسواق (`froms` / `tos`)

مرشحات إشارات التوسع

البيانات الوصفية للشركة

النافذة الزمنية والبحث

حقول الاستجابة

`stage` لكل شركة/سوق

الإشارات والحضور والتفسير