> ## 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 الحية.
</Info>

## السيناريو

أنت تبيع لشركات تُنشئ عمليات في **المملكة المتحدة**. تريد أحدث المتحركين الواردين، ثم تريد فهم *لماذا* تتوسع إحداها حتى تتمكن من توقيت تواصلك.

## الخطوة 1 — إيجاد أحدث المتحركين الواردين إلى المملكة المتحدة

اضبط `tos: ["GB"]` لإيجاد كل شركة تتوسع **إلى** المملكة المتحدة، بالإضافة إلى مرشح حداثة بحيث ترى فقط الشركات التي تصل حاليًا.

```bash theme={null}
POST /expansions/search
{
  "tos": ["GB"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}
```

تلخّص الاستجابة السوق وتسرد الشركات المتوسعة إليه:

```json theme={null}
{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] },
    "aggregate": { "total_companies_with_signals": 64, "committing_count": 22, "expanding_count": 15 },
    "top_origins": [{ "home_country_code": "CN", "company_count": 18 }],
    "top_industries": [{ "industry": "Consumer Electronics", "count": 9 }]
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [
      {
        "expansion_id": "6845525",
        "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
        "company_name": "Example Corp",
        "domain": "example.com",
        "home_country_code": "CN",
        "country_code": "GB",
        "industry": "Consumer Electronics",
        "stage": { "slug": "expanding", "expansion_score": 0.72, "scope": "entering_new_market", "direction": "advancing", "freshness": "fresh", "signal_count": 7 }
      }
    ]
  }
}
```

رتّب حسب `expansion_score` لوضع أكثر المتحركين حسمًا أولًا. هنا، شركة مقرها الصين (`home_country_code: "CN"`) في مرحلة **التوسع** (`expanding`) في المملكة المتحدة بمسار **متقدم** — تحرك وارد قوي وحديث.

<Frame caption="القائمة المرتبة نفسها، داخل المنتج — المرحلة والزخم والحداثة في لمحة واحدة، لكل شركة تطابق مرشحاتك.">
  <img src="https://mintcdn.com/pubrio/D7-S_msGUHbXRYZf/images/expansion/company-list.png?fit=max&auto=format&n=D7-S_msGUHbXRYZf&q=85&s=68065a3ddfa43c7743cd2952e9cac6c5" alt="قائمة مرتبة لشركات تتوسع إلى سوق، تعرض كل منها مرحلتها وسهم زخمها وحداثتها وعدد إشاراتها" width="3024" height="1568" data-path="images/expansion/company-list.png" />
</Frame>

## الخطوة 2 — اطّلع على خريطة السوق الكاملة للشركة

خذ `domain_search_id` واسرد كل سوق تتوسع إليه تلك الشركة.

```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 }
  ]
}
```

الشركة تتوسع إلى المملكة المتحدة وتلتزم بموارد في ألمانيا — سياق مفيد لترتيب أولوية المنطقة المناسبة.

<Frame caption="شركة واحدة، وكل سوق تتحرك نحوها، موضَّحة على الخريطة — الصفان نفسهما اللذان وصفهما JSON أعلاه.">
  <img src="https://mintcdn.com/pubrio/D7-S_msGUHbXRYZf/images/expansion/global-expansion-map.png?fit=max&auto=format&n=D7-S_msGUHbXRYZf&q=85&s=2b2d2c846fc700626e4041942149e96e" alt="أسواق شركة واحدة موضَّحة على خريطة عالمية، ملوَّنة حسب المرحلة، مع مفتاح مراحل وموجز نشاط حديث" width="3022" height="1570" data-path="images/expansion/global-expansion-map.png" />
</Frame>

## الخطوة 3 — افهم تحرك المملكة المتحدة بعمق

تعمّق في تفاصيل الشركة والسوق لرؤية المرحلة الحالية، والإشارات الأساسية، والحضور المعروف، والجدول الزمني للانتقال.

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

```json theme={null}
{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "country_code": "GB" },
  "data": {
    "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
    "country_code": "GB",
    "country_name": "United Kingdom",
    "stage_rank": 3,
    "stage_name": "Expanding",
    "stage": { "slug": "expanding", "expansion_score": 0.72, "scope": "entering_new_market", "direction": "advancing", "freshness": "fresh", "signal_count": 27 }
  },
  "signals": [
    {
      "signal_type_slug": "EXEC",
      "display_label": "Hired Regional VP for UK & Ireland",
      "polarity": "expansion",
      "event_date": "2026-06-20T14:00:00.000Z"
    }
  ],
  "presence": [
    { "presence_type": "office", "address": "London, UK", "known_since": "2026-03-15T00:00:00.000Z" }
  ]
}
```

مرحلة التوسع مدعومة بتوظيف قيادي بارز في المملكة المتحدة ومكتب في لندن — دليل ملموس، لا تخمين.

## الخطوة 4 — اقرأ الأحداث الفردية

للحصول على القائمة الكاملة والمرقّمة صفحيًا للأحداث الدافعة للتحرك، استدعِ نقطة أحداث الإشارة بأنواع الإشارات التي تهمك.

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

```json theme={null}
{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002" },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 42, "total_pages": 2, "total_display_pages": 2, "is_timeout": false },
    "events": [
      {
        "signal_type_slug": "EXEC",
        "country_code": "GB",
        "display_label": "Hired Regional VP for UK & Ireland",
        "evidence_url": "https://www.linkedin.com/company/example-corp",
        "event_date": "2026-06-20T14:00:00.000Z"
      }
    ]
  }
}
```

استخدم `total_pages` لتشغيل عنصر تحكم "تحميل المزيد" بزيادة `page` حتى يبلغ `total_pages`.

<Frame caption="الأحداث نفسها، كل منها بدليله — بصمة سحابية مكتشَفة، أو تعيين تنفيذي، أو سلسلة إعلانات مستهدفة جغرافيًا.">
  <img src="https://mintcdn.com/pubrio/D7-S_msGUHbXRYZf/images/expansion/signal-drawer.png?fit=max&auto=format&n=D7-S_msGUHbXRYZf&q=85&s=621f62b0e5c3a2ba3ea0731c3a3833fe" alt="موجز إشارات توسع فردية لشركة واحدة في سوق واحدة، كل إشارة بنوعها ورابط دليلها وتاريخها" width="3022" height="1576" data-path="images/expansion/signal-drawer.png" />
</Frame>

## ما فعلته للتو

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

<CardGroup cols={2}>
  <Card title="استخدام Expansion API" href="/ar/knowledge-base/concepts/expansion-api-quickstart">
    المصادقة، والترقيم الصفحي، وأول استدعاءاتك.
  </Card>

  <Card title="كيف تعمل إشارات التوسع" href="/ar/knowledge-base/concepts/how-expansion-signals-work">
    الكتالوج الكامل للقيم المستخدمة أعلاه.
  </Card>
</CardGroup>