> ## 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

> صادِق، ونفّذ أول استدعاءات Expansion API الخاصة بك، ورقِّم النتائج صفحيًا، واقرأ درجات التوسع.

<Info>
  تنقلك هذه البداية السريعة من الصفر إلى قراءة إشارات توسع حية في بضعة استدعاءات. تفترض أن لديك بالفعل مفتاح Pubrio API — راجع [المصادقة](/ar/api-reference/authentication) لإنشاء واحد.
</Info>

## المتطلبات الأساسية

* مفتاح Pubrio API (راجع [المصادقة](/ar/api-reference/authentication)).
* `domain_search_id` لشركة ما. يمكنك الحصول عليه من نقطة [البحث عن الشركات](/ar/api-reference/endpoint/companies/search).

جميع نقاط Expansion الطرفية هي `POST` وتقبل جسم JSON. أدرِج بيانات اعتمادك في كل طلب كما هو موضَّح في [المصادقة](/ar/api-reference/authentication).

## الخطوة 1 — البحث عن توسع شركة

ابدأ بشركة واحدة واسرد كل سوق تتوسع فيه.

```bash theme={null}
POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }
```

```json theme={null}
{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}
```

## الخطوة 2 — اقرأ النتيجة

يصف كل إدخال في `markets_summary` سوقًا واحدًا تنشط فيه الشركة:

* **`stage_slug`** — مدى تقدم الشركة هناك (`exploring` → `scaling`).
* **`signal_count`** / **`distinct_type_count`** — كمية الأدلة الداعمة للسوق، وعبر كم نوع من الإشارات.
* **`latest_signal_at`** — حداثة أحدث إشارة.
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — مدى سرعة تصاعد النشاط.
* **`rank_now`** — الترتيب الحالي للسوق بالنسبة لهذه الشركة (`1` = الأقوى).
* **`is_home_market`** — ما إذا كانت هذه دولة مقر الشركة.

لإظهار أحدث المتحركين أو التصفية حسب المسار، استخدم نقاط الاكتشاف (`freshness`، `momentum`) الموضَّحة تاليًا.

## الخطوة 3 — استكشف سوقًا بأكمله

للعمل بمنطق السوق أولًا بدلًا من الشركة أولًا، استخدم [تفاصيل سوق التوسع](/ar/api-reference/endpoint/expansions/market_lookup). وهي مرقّمة صفحيًا بالمعاملات القياسية `page` / `per_page`.

الجغرافيا هي علاقة موجَّهة **من → إلى**، معبَّر عنها بقائمتين: `froms` (أسواق المنشأ/المقر) و`tos` (الأسواق المستهدفة). اختر النمط الذي يطابق سؤالك:

<CodeGroup>
  ```bash وارد (إلى GB) theme={null}
  POST /expansions/search
  {
    "tos": ["GB"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash صادر (من CN) theme={null}
  POST /expansions/search
  {
    "froms": ["CN"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash ممر (CN → GB) theme={null}
  POST /expansions/search
  {
    "froms": ["CN"],
    "tos": ["GB"],
    "page": 1,
    "per_page": 25
  }
  ```
</CodeGroup>

اقرأ `metadata.pagination` للتنقل عبر صفحات النتائج:

```json theme={null}
{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] }
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [ /* ... */ ]
  }
}
```

اطلب الصفحة التالية بزيادة `page`. `per_page` محدود حسب خطتك — طلب أكثر من حدك صراحة يُعيد خطأً بدلًا من الاقتطاع بصمت.

افتراضيان يستحقان المعرفة:

* **الترتيب** — تعود النتائج بترتيب الصلة (الشركات المدعَّمة بعدة أنواع إشارات أولًا، ثم الأحدث). مرّر `sort_by: "recent"` للحداثة الصرفة، أو `expansion_score` / `signal_count` / `company_ranking`.
* **استجابات مختصرة** — تحذف استجابات مفتاح API تجميع السوق (`metadata.aggregate`، أهم المصادر/الوجهات، الجدول الزمني) وتفاصيل النموذج افتراضيًا. مرّر `is_include_metadata: true` عندما تريدها.

## الخطوة 4 — تعمّق في الأدلة

عندما تريد الإشارات الفردية وراء تحرك شركة، استدعِ [أحداث إشارات الشركة](/ar/api-reference/endpoint/expansions/company_pulse_events).

```bash theme={null}
POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC", "NEWS"],
  "window_days": 90,
  "page": 1
}
```

تُعيد هذه النقطة الطرفية `total_entries` و`total_pages` — اطلب الصفحات من `1` إلى `total_pages` (أي استمر طالما `page` \< `total_pages`).

## مرجع التصفية

تقبل معظم نقاط التوسع الطرفية هذه المرشحات. قيمها الصالحة مدرجة في [كيف تعمل إشارات التوسع](/ar/knowledge-base/concepts/how-expansion-signals-work):

| المرشح         | الغرض                                                                   |
| -------------- | ----------------------------------------------------------------------- |
| `stages`       | التحديد لمرحلة توسع واحدة أو أكثر.                                      |
| `freshness`    | التحديد حسب حداثة الأدلة.                                               |
| `momentum`     | التحديد حسب المسار (`advancing`/`steady`/`pulling_back`).               |
| `scopes`       | التحديد حسب نطاق دخول السوق.                                            |
| `signal_types` | التحديد لأنواع إشارات محددة.                                            |
| `froms`        | أسواق المنشأ/المقر (التوسع **من**).                                     |
| `tos`          | الأسواق المستهدفة (التوسع **إلى**).                                     |
| `companies`    | التحديد لشركات محددة عبر `domain_search_id` أو النطاق أو رابط LinkedIn. |

يقبل مرشح `companies` أي مزيج من أنواع المعرّفات — دون الحاجة لحلها إلى معرّفات أولًا:

<CodeGroup>
  ```bash حسب النطاق theme={null}
  POST /expansions/search
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

  ```bash حسب رابط LinkedIn theme={null}
  POST /expansions/search
  { "companies": ["https://www.linkedin.com/company/stripe"] }
  ```

  ```bash حسب domain_search_id theme={null}
  POST /expansions/search
  { "companies": ["550e8400-e29b-41d4-a716-446655440002"] }
  ```
</CodeGroup>

<Warning>
  لا تخلط بين **التدفق** و**المسار**. التدفق (اتجاه التحرك بين الأسواق) يُحدَّد بـ `froms` / `tos` — لا يوجد مرشح طلب باسم `direction`. أما المسار (كيف يتقدم التحرك) فهو مرشح `momentum`، ويظهر في الاستجابات كحقل `direction`.
</Warning>

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="مثال عملي" href="/ar/knowledge-base/concepts/expansion-signals-example">
    الشرح الكامل من السوق إلى الإشارة.
  </Card>

  <Card title="نقاط التوسع الطرفية" href="/ar/api-reference/endpoint/expansions/dashboard">
    تصفّح كل نقطة طرفية في Expansion API.
  </Card>
</CardGroup>