استخدام Expansion API

تنقلك هذه البداية السريعة من الصفر إلى قراءة إشارات توسع حية في بضعة استدعاءات. تفترض أن لديك بالفعل مفتاح Pubrio API — راجع المصادقة لإنشاء واحد.

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

مفتاح Pubrio API (راجع المصادقة).
domain_search_id لشركة ما. يمكنك الحصول عليه من نقطة البحث عن الشركات.

جميع نقاط Expansion الطرفية هي POST وتقبل جسم JSON. أدرِج بيانات اعتمادك في كل طلب كما هو موضَّح في المصادقة.

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

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

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

{
  "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 — استكشف سوقًا بأكمله

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

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

POST /expansions/search
{
  "froms": ["CN"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "tos": ["GB"],
  "page": 1,
  "per_page": 25
}

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

{
  "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 — تعمّق في الأدلة

عندما تريد الإشارات الفردية وراء تحرك شركة، استدعِ أحداث إشارات الشركة.

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).

مرجع التصفية

تقبل معظم نقاط التوسع الطرفية هذه المرشحات. قيمها الصالحة مدرجة في كيف تعمل إشارات التوسع:

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

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

POST /expansions/search
{ "companies": ["stripe.com", "airbnb.com"] }

POST /expansions/search
{ "companies": ["https://www.linkedin.com/company/stripe"] }

POST /expansions/search
{ "companies": ["550e8400-e29b-41d4-a716-446655440002"] }

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

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

الأدلة

المفاهيم

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

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

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

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

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

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

مرجع التصفية

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

مثال عملي

نقاط التوسع الطرفية

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

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

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

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

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

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

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

مثال عملي

نقاط التوسع الطرفية

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

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

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

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

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

مرجع التصفية

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