نظرة عامة على الفلاتر

تشترك نقاط نهاية البحث في Pubrio (/companies/search، /people/search، /companies/advertisements/search) في محرك فلاتر واحد. تُنشئ نص الطلب مرة واحدة وتنطبق القواعد نفسها عبر نقاط النهاية — بما في ذلك طريقة دمج الفلاتر متعددة القيم، وكيفية مطابقة المواقع، وكيفية تجاوز المعامل الافتراضي عبر filter_conditions.

لماذا محرك فلاتر موحّد؟

مخطط واحد، ثلاث نقاط نهاية

فلاتر مستوى الشركة مثل technologies وverticals وfounded_dates تعمل بنفس الطريقة على /companies/search و/people/search وداخل company_filters في Monitor — تتعلمها مرة واحدة.

AND/OR لكل فلتر

القيمة الافتراضية هي OR (مطابقة أي قيمة). ارفع فلاترًا فردية إلى AND (مطابقة الكل) بإضافة عبارة واحدة إلى filter_conditions — دون المساس ببقية نص الطلب.

تصفية قبل التنقل بين الصفحات

يُطبَّق كل فلتر قبل إرجاع النتائج، لذا تعكس كل صفحة وكل إجمالي طلبك بأكمله. دون تصفية إضافية من جهة التطبيق.

نفس الفلاتر في Monitors

تقبل كتلة company_filters في Monitors الشكل نفسه، لذا فإن حمولة بحث تعمل هي أيضًا حمولة Monitor صالحة.

تشريح طلب بحث

يُبنى كل طلب بحث من ثلاث طبقات في نفس نص JSON:

الطبقة	مكانها	أمثلة
فلاتر الأشخاص	مفاتيح المستوى الأعلى	`people_titles`، `management_levels`، `departments`، `people_locations`
فلاتر الشركة	متداخلة تحت `company_filters: {...}` (موصى به) — تُقبل أيضًا في المستوى الأعلى	`technologies`، `verticals`، `founded_dates`، `employees`، `company_locations`
تجاوزات المعامل	مصفوفة `filter_conditions` (داخل `company_filters` عند تجاوز مفاتيح الشركة)	`[{ "key": "technologies", "operator": "and" }]`

طلب /people/search بسيط يستخدم الطبقات الثلاث جميعًا:

curl -X POST https://api.pubrio.com/people/search \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "people_titles": ["VP of Engineering", "CTO"],
    "company_filters": {
      "technologies": ["Kubernetes", "Docker"],
      "is_enable_similarity_search": true,
      "company_locations": ["US"]
    },
    "per_page": 25,
    "page": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/people/search",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY",
    },
    json={
        "people_titles": ["VP of Engineering", "CTO"],
        "company_filters": {
            "technologies": ["Kubernetes", "Docker"],
            "is_enable_similarity_search": True,
            "company_locations": ["US"],
        },
        "per_page": 25,
        "page": 1,
    },
)
print(response.json())

const response = await fetch("https://api.pubrio.com/people/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    people_titles: ["VP of Engineering", "CTO"],
    company_filters: {
      technologies: ["Kubernetes", "Docker"],
      is_enable_similarity_search: true,
      company_locations: ["US"],
    },
    per_page: 25,
    page: 1,
  }),
});
console.log(await response.json());

`company_filters`: إبقاء مفاتيح الشركة مجمّعة

كائن الغلاف company_filters: {...} هو الطريقة الموصى بها لإرسال فلاتر مستوى الشركة — فهو يفصل بصريًا بين المفاتيح التي تصفّي الشخص والمفاتيح التي تصفّي الشركة، ويطابق الشكل الذي تستخدمه Monitors بالفعل، بحيث تنتقل الحمولات بسلاسة بين إعدادات البحث وMonitor. كلا الأسلوبين يعمل؛ يُسطِّح المحرك الشكل المُغلَّف إلى المستوى الأعلى قبل المعالجة، وتفوز مفاتيح المستوى الأعلى عند التعارض:

{
  "people_titles": ["VP of Engineering"],
  "company_filters": {
    "technologies": [10191, 121],
    "founded_dates": [2015, 2023],
    "company_locations": ["US"]
  }
}

{
  "people_titles": ["VP of Engineering"],
  "technologies": [10191, 121],
  "founded_dates": [2015, 2023],
  "company_locations": ["US"]
}

عند إضافة تجاوز filter_conditions لمفتاح على مستوى الشركة، ضعه داخل company_filters كي ينتقل مع المفاتيح التي يتجاوزها.

نفس الشكل في نسختي `/search/similar`

تقبل POST /companies/search/similar وPOST /people/search/similar نفس نص الفلاتر الذي تقبله النسختان غير المشابهتان (بما في ذلك غلاف company_filters وfilter_conditions). تضيف كل نقطة نهاية خطوة تشابه فوق ذلك:

	ما تحتاجه إضافيًا	ما تحصل عليه إضافيًا
`/companies/search/similar`	شركة مرجعية — `domain_search_id`، `domain`، أو `linkedin_url`	تحصل كل نتيجة على `similarity_score` (عدد عشري، 0-1)
`/people/search/similar`	شخص/مسمى وظيفي مرجعي — واحد من `people_titles`، `people_search_id`، `linkedin_url`، `linkedin_urls`، أو `peoples`	الأشخاص الأقرب إلى مرجعك — تحصل كل نتيجة على `similarity_score` (عدد عشري، 0-1)

تُضيّق الفلاتر مجموعة المرشحين قبل تطبيق التشابه — لذا فإن دمج company_locations: ["US"] مع /people/search/similar يُرجع أقرب الأشخاص في الولايات المتحدة إلى مسمياتك الوظيفية المرجعية، وهو نمط “ابحث عن المزيد من الأشخاص المشابهين لـ X ضمن هذه القيود”.

تُرجع /companies/search/similar الحقل data كمصفوفة بسيطة من الشركات — لا يوجد كائن pagination. تنقّل بين النتائج باستخدام page وper_page. استخدم البحث بالتشابه لإيجاد أفضل التطابقات، وليس لحصر كل واحدة منها.

AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

تقبل الفلاتر متعددة القيم (technologies، verticals، keywords، categories، …) مصفوفة. يحدد المعامل معنى “المطابقة”:

OR (الافتراضي)
AND

مطابقة أي قيمة. يُرجع الصفوف التي تتداخل مصفوفتها مع المدخلات.

{
  "technologies": ["Python", "PostgreSQL", "Kubernetes"],
  "is_enable_similarity_search": true
}

تُدرَج الشركة إذا كانت حزمة تقنياتها تحتوي على قيمة واحدة على الأقل من Python أو PostgreSQL أو Kubernetes.استخدمها عندما: تريد نطاقًا واسعًا — “مهتم بـ أي من هذه”، “موجود في أي من هذه الدول”.

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

{
  "technologies": [10191, 121],
  "filter_conditions": [
    { "key": "technologies", "operator": "and" }
  ]
}

تأتي معرّفات الوسم الرقمية من POST /technologies مع keyword (ومن نقاط النهاية المقابلة للقطاعات والفئات). مع الأسماء النصية الحرة وAND، يجب أن تطابق الشركة كل اسم أدرجته.تُدرَج الشركة فقط إذا كانت حزمة تقنياتها تحتوي على كل قيم [10191, 121] (Salesforce وHubSpot).استخدمها عندما: تريد الدقة — “تستخدم كل هذه التقنيات معًا”، “موسومة بـ كل هذه القطاعات”.

الفلاتر غير المدرجة في filter_conditions تستخدم المعامل الافتراضي (OR داخل المصفوفة، AND بين مفاتيح الفلاتر المختلفة). تُعلن فقط التجاوزات — لا تحتاج أبدًا إلى كتابة القيم الافتراضية.

ما يمكنك تجاوزه

تقبل كل نقطة نهاية تجاوزات لمجموعة مختلفة من المفاتيح. تأتي المفاتيح من تعداد OpenAPI في كل مخطط *_filter_conditions:

نقطة نهاية الشركة

مفاتيح company_filter_conditions: keywords، verticals، vertical_categories، vertical_sub_categories، technologies، categories، social_media، advertisement_target_locations، job_exclude_locations.

نقطة نهاية الأشخاص

مفاتيح people_filter_conditions: keywords، verticals، vertical_categories، vertical_sub_categories، technologies، categories، social_media.

نقطة نهاية الإعلانات

مفاتيح ads_filter_conditions: target_locations، publisher_platforms.

فلاتر المواقع والأماكن تطابق دائمًا أي قيمة مدرجة، في كل نقطة نهاية. لا تغيّرها filter_conditions.

نصائح للأداء

ابدأ بأضيق الفلاتر

المواقع، ونطاقات عدد الموظفين، وfounded_dates تُقلِّص مجموعة المرشحين أسرع من الفلاتر النصية الحرة أو فلاتر القطاعات. اجمعها مع فلتر أو فلترين دقيقين قبل اللجوء إلى البحث بالتشابه.

لا تُفرِط في استخدام AND على مصفوفات كبيرة

يتطلب AND أن تكون كل قيمة موجودة. تطبيق AND على 10 تقنيات يُرجع صفوفًا قريبة من الصفر. فضِّل 2-4 قيم لكل فلتر AND؛ وانتقل إلى OR للاستعلامات الاستكشافية.

استخدم is_enable_similarity_search للمدخلات النصية الحرة

إذا تعذّر عليك توفير معرّفات slug (للقطاعات، والتقنيات، والفئات) ولديك فقط سلاسل نصية حرة، اضبط is_enable_similarity_search: true وsimilarity_score: 0.7. يحلّ المحرك التطابقات قبل تطبيق الفلتر — أرخص بكثير من فحص النص.

فضِّل النطاقات على قوائم التعداد للحجم والإيرادات

employees: [[201, 500], [501, 1000]] (مصفوفة من الفئات) وrevenues: [1000000, 5000000] (نطاق أدنى/أعلى واحد) أسرع وأكثر توافقًا مع الأسلوب من قوائم المعرّفات الطويلة.

فلاتر النشاط الإعلاني

يمكن لـ /companies/search التصفية حسب البصمة الإعلانية للشركة — عدد الإعلانات التي تُشغّلها، وما إذا كان أي منها نشطًا حاليًا، والمنصات والصيغ التي تستخدمها، وترتيبها مقارنةً بالمعلنين الآخرين في دولة معينة. تقبل POST /companies/advertisements/search كل هذه الفلاتر أيضًا (advertisement_active_ads، advertisement_running_ads، advertisement_total_ads، advertisement_platform_count، advertisement_format_count، advertisement_impressions_estimate، advertisement_formats، advertisement_country_activity) — يُدرَج الإعلان إذا استوفت الشركة المالكة له الشرط.

الفلتر	الشكل	النطاق
`advertisement_active_ads`، `advertisement_running_ads`، `advertisement_total_ads`	نطاق `[min, max]`	كل الدول
`advertisement_platform_count`، `advertisement_format_count`	نطاق `[min, max]`	كل الدول
`advertisement_impressions_estimate`	نطاق `[min, max]`	كل الدول
`advertisement_formats`	مصفوفة — `image`، `video`، `text`، `carousel`، `dynamic_product`، `document`، `message`، `event`، `article`، `spotlight`، `follow`، `job`، `engagement`	كل الدول
`advertisement_platforms`	مصفوفة — `linkedin`، `facebook`، `google`، `tiktok`، `apple` (تُقبل `meta` كاسم بديل لـ `facebook`)	كل الدول
`advertisement_publisher_platforms`، `advertisement_exclude_publisher_platforms`	مصفوفة — `facebook`، `instagram`، `messenger`، `threads`، `audience_network`	كل الدول
`advertisement_status`	مصفوفة — `currently_running` (لديها إعلانات مسجَّلة)، `active_last_30_min` (تغيّرت سجلات الإعلان خلال آخر 30 دقيقة)	كل الدول
`advertisement_country_activity`	كائن، انظر أدناه	دولة واحدة

استخدم null لحد مفتوح — [1, null] تعني “على الأقل 1”، و[null, 500] تعني “500 أو أقل”.

{
  "advertisement_active_ads": [1, null],
  "advertisement_formats": ["video"]
}

الترتيب داخل دولة

يحدّد advertisement_country_activity نطاق الترتيب والمئوية ودرجة الحجم لدولة واحدة في كل مرة — لأن ترتيب إعلانات شركة في الولايات المتحدة لا يقول شيئًا عن ترتيبها في ألمانيا، لذا فإن country مطلوب:

{
  "advertisement_country_activity": {
    "country": "US",
    "rank": [null, 500]
  }
}

يُحسَب rank تنازليًا بدءًا من أكبر منفِق، تمامًا مثل ترتيب سباق. الرقم 1 هو أكبر معلن في تلك الدولة، ويرتفع الرقم كلما انخفض حجم الإنفاق الإعلاني. للعثور على أكبر المنفقين، صفِّ rank بحد أعلى منخفض — [null, 500] هي أفضل 500. أما تصفية [500, null] فتجد كل من هم خارج أفضل 499، وهو عكس معنى “منفق كبير”. إذا أردت مقياسًا مستقلًا عن الحجم يعمل بالطريقة نفسها بغض النظر عن عدد المعلنين في تلك الدولة، استخدم percentile بدلًا من ذلك — فهو يعمل بالاتجاه المعاكس، بحيث يعني الرقم الأعلى منفقًا أكبر: [90, null] هي أفضل 10%.

يمكنك دمج advertisement_country_activity مع الفلاتر السارية على كل الدول أعلاه في نفس الطلب — على سبيل المثال، “مرتبة ضمن أفضل 500 في الولايات المتحدة، ولديها 100 إعلان نشط على الأقل على مستوى الشركة”:

{
  "advertisement_country_activity": { "country": "US", "rank": [null, 500] },
  "advertisement_active_ads": [100, null]
}

ترتيب النتائج

تحصر التصفية بـ advertisement_country_activity أي الشركات تُعاد؛ لكنها لا تحدّد الترتيب بحد ذاتها. للحصول على أكبر المعلنين في ذلك السوق أولًا، اطلب sort_by: "advertisement_country_rank":

{
  "advertisement_country_activity": { "country": "HK", "rank": [1, 10] },
  "sort_by": "advertisement_country_rank"
}

كلما كان advertisement_country_activity موجودًا، تحمل كل شركة أيضًا مكانتها في تلك الدولة، بحيث يمكنك عرض الترتيب الذي صفّيت به:

الحقل	المعنى
`advertisement_country_rank`	الموضع في تلك الدولة، 1 = أكبر معلن. تتشارك الحالات المتعادلة الترتيب نفسه، لذا قد تتكرر الأرقام ثم تقفز.
`advertisement_country_percentile`	نسبة المعلنين في تلك الدولة الذين تتفوق عليهم هذه الشركة.
`advertisement_country_active_ads`	الإعلانات النشطة المنسوبة إلى تلك الدولة — وليس `advertisement_active_ads` على مستوى الشركة.

يُتجاهَل sort_by: "advertisement_country_rank" عند غياب advertisement_country_activity، لأن الترتيب لا يوجد إلا داخل دولة. مرّر is_ascending_order: false لسرد أصغر المعلنين في السوق أولًا.

العثور على الداخلين الجدد إلى السوق

يقبل advertisement_country_activity أيضًا نافذتَي تاريخ، بحيث يمكنك السؤال عمّن بدأ الإعلان في سوق ما بدلًا من مَن هو كبير فيه بالفعل:

المفتاح	المعنى
`first_seen`	`[from, to]` — متى عُرض أول إعلان للشركة في تلك الدولة. هذا هو مرشّح «دخلت هذا السوق حديثًا».
`last_seen`	`[from, to]` — متى عُرض أحدث إعلان لها في تلك الدولة. مفيد للسؤال المعاكس: من توقّف نشاطه.

الشركات التي دخلت اليابان منذ بداية يوليو:

{
  "advertisement_country_activity": { "country": "JP", "first_seen": ["2026-07-01", null] }
}

يمكن ترك أي من الحدين null للحصول على نافذة مفتوحة. تُفسَّر التواريخ حسب المنطقة الزمنية للطلب. الشركة التي لا تحمل إعلاناتها تاريخ بدء ليس لها قيمة أول رصد وتُعامَل على أنها غير معروفة — ولا تُعتبر جديدة أبدًا. ادمج ذلك مع مفاتيح الترتيب في نفس الكائن لتضييق النطاق أكثر، مثلًا الداخلون الجدد الذين ينفقون بكثافة بالفعل.

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

filter_conditions

صفحة مرجعية — كل مفتاح مدعوم، وكل قيمة افتراضية، ووصفات AND/OR جاهزة للنسخ.

فلاتر الأشخاص + الشركة

استخدم أي فلتر شركة داخل /people/search. الميزة الجديدة الأبرز للمحرك الموحّد.

مرجع بحث الشركات

مخطط الطلب/الاستجابة الكامل لـ /companies/search.

مرجع بحث الأشخاص

مخطط الطلب/الاستجابة الكامل لـ /people/search.

تبحث عن شرح التصفية من جانب لوحة التحكم؟ انظر تصفية جهات الاتصال وتصديرها في قاعدة المعرفة.

Monitor

البحث

المرشحات

الأشخاص

التوسع

نظرة عامة على الفلاتر

لماذا محرك فلاتر موحّد؟

مخطط واحد، ثلاث نقاط نهاية

AND/OR لكل فلتر

تصفية قبل التنقل بين الصفحات

نفس الفلاتر في Monitors

تشريح طلب بحث

`company_filters`: إبقاء مفاتيح الشركة مجمّعة

نفس الشكل في نسختي `/search/similar`

AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

ما يمكنك تجاوزه

نقطة نهاية الشركة

نقطة نهاية الأشخاص

نقطة نهاية الإعلانات

نصائح للأداء

فلاتر النشاط الإعلاني

الترتيب داخل دولة

ترتيب النتائج

العثور على الداخلين الجدد إلى السوق

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

filter_conditions

فلاتر الأشخاص + الشركة

مرجع بحث الشركات

مرجع بحث الأشخاص

​لماذا محرك فلاتر موحّد؟

مخطط واحد، ثلاث نقاط نهاية

AND/OR لكل فلتر

تصفية قبل التنقل بين الصفحات

نفس الفلاتر في Monitors

​تشريح طلب بحث

​company_filters: إبقاء مفاتيح الشركة مجمّعة

​نفس الشكل في نسختي /search/similar

​AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

​ما يمكنك تجاوزه

نقطة نهاية الشركة

نقطة نهاية الأشخاص

نقطة نهاية الإعلانات

​نصائح للأداء

​فلاتر النشاط الإعلاني

​الترتيب داخل دولة

​ترتيب النتائج

​العثور على الداخلين الجدد إلى السوق

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

filter_conditions

فلاتر الأشخاص + الشركة

مرجع بحث الشركات

مرجع بحث الأشخاص

لماذا محرك فلاتر موحّد؟

تشريح طلب بحث

`company_filters`: إبقاء مفاتيح الشركة مجمّعة

نفس الشكل في نسختي `/search/similar`

AND مقابل OR — القرار الوحيد الذي تتخذه لكل فلتر

ما يمكنك تجاوزه

نصائح للأداء

فلاتر النشاط الإعلاني

الترتيب داخل دولة

ترتيب النتائج

العثور على الداخلين الجدد إلى السوق

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