> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> قاموس حقل بحقل لواجهة Expansion API — كل مرشح طلب وحقل استجابة، ونوعه، والقيم المسموح بها، ومعناه.

<Info>
  هذا هو **قاموس الحقول** لواجهة Expansion API: ما تفعله كل مرشح طلب وما يعنيه كل حقل استجابة. لمعرفة *سبب* بناء النموذج على هذا النحو، راجع [كيف تعمل إشارات التوسع](/ar/knowledge-base/concepts/how-expansion-signals-work) وكتالوج القيم في [كيف تعمل إشارات التوسع](/ar/knowledge-base/concepts/how-expansion-signals-work). للحصول على قائمة محدَّثة دائمًا بالقيم المسموح بها، استدعِ نقطة [تصنيف التوسع](/ar/api-reference/endpoint/expansions/types).
</Info>

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

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

| الحقل             | ما يلتقطه                                                     | قيم نموذجية                                                            |
| ----------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `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`                                                                 |

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

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

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

### الأسواق (`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` لإشارة فردية حقيقية، أو عدد صحيح عندما يكون الاستشهاد عد حجم محدَّد بنافذة (إعلانات الوظائف، الحملات الإعلانية) بدلًا من حدث واحد. |

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