البحث في الإعلانات

يُعيد البحث في الإعلانات إعلانات فردية التقطها Pubrio، صفًا واحدًا لكل إعلان. يحمل كل صف الإبداع (العنوان، الصورة أو الفيديو، صفحة الهبوط)، ومكان عرضه، ووقت تشغيله، ونطاق الانطباعات الذي يبلّغ عنه المصدر.

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com"],
    "source_types": ["linkedin", "facebook"],
    "active_dates": ["2026-08-01", "2026-08-31"],
    "per_page": 25
  }'

متى تستخدمه

بحث تنافسي في المحتوى الإبداعي — ما الذي يقوله منافسك، وفي أي دول، وبأي صيغة.
النية — الشركة التي بدأت للتو الإعلان في سوق جديدة تكون بصدد التوسع فيها. اجمعه مع target_locations.
مؤشرات بديلة للإنفاق — تصنّف reach_tiers ومرشحات المقاييس advertisement_* الشركات حسب حجم الإعلان دون رقم إنفاق فعلي.

للحصول على الإجماليات والاتجاهات استخدم رؤى الإعلانات. ولإيجاد الشركات حسب نشاطها الإعلاني بدلًا من الإعلانات نفسها، استخدم مرشحات advertisement_* في البحث عن الشركات.

المصادر

`source_type`	ملاحظات
`linkedin`	تصنيفات صيغة غنية (`Single Image Ad`، `Document Ad`، …)
`facebook`	يشمل Facebook وInstagram وMessenger وThreads وAudience Network؛ ضيّق النطاق باستخدام `publisher_platforms`. تُقبل `meta` كاسم بديل.
`google`	غالبًا `text`
`tiktok`
`apple`

تكون total_impressions بقيمة null في الإعلانات التي لا ينشر مصدرها أي تقدير، ولا تطابق هذه الإعلانات reach_tiers أبدًا.

التحديد بشركة

المفتاح	القيمة
`domains`	`["stripe.com"]`
`linkedin_urls`	`["https://www.linkedin.com/company/stripe"]`
`companies`	`["5378845d-…"]` — قيم `domain_search_id`

يُسمح بالبحث دون تحديد شركة، مثل {"target_locations": ["SG"], "source_types": ["linkedin"]}. لا تُعاد إلا الإعلانات المرتبطة فعلًا بشركة في Pubrio ما لم تضبط is_include_unlinked_companies: true.

المرشحات

المصدر والصيغة

المفتاح	النوع	يطابق
`source_types`	`string[]`	`linkedin`، `facebook`، `google`، `tiktok`، `apple`. أي قيمة مذكورة. القيم غير المعروفة لا تطابق شيئًا وتُعرض في `metadata.unsupported_source_types`.
`exclude_source_types`	`string[]`	نفس المفردات، لكن للاستبعاد.
`advertisement_formats`	`string[]`	الصيغ القياسية: `image`، `video`، `text`، `carousel`، `dynamic_product`، `document`، `message`، `event`، `article`، `spotlight`، `follow`، `job`، `engagement`. انظر الصيغ.
`publisher_platforms` / `exclude_publisher_platforms`	`string[]`	`facebook`، `instagram`، `messenger`، `threads`، `audience_network`. إعلانات Meta فقط.

النص

المفتاح	النوع	يطابق
`headlines`	`string[]`	نص العنوان، أي قيمة مذكورة.
`search_term` / `search_terms`	`string` / `string[]`	العنوان والوصف.

التواريخ

المفتاح	النوع	يطابق
`active_dates`	`[from, to]`	الإعلانات النشطة في أي لحظة ضمن النافذة، بما فيها الإعلانات التي بدأت قبل ذلك ولا تزال حية. هذه هي النافذة التي تستخدمها رؤى الإعلانات. الإعلانات التي لا تحمل `started_at` تُحتسب من `created_at`. كلا التاريخين مطلوب؛ حدود اليوم بتوقيت UTC.
`start_dates`	`[from, to]`	`started_at` ضمن النافذة — الإعلانات التي انطلقت حينها. حدود اليوم بتوقيت منطقة عمل حسابك.
`end_dates`	`[from, to]`	`ended_at` ضمن النافذة. حدود اليوم بتوقيت منطقة عمل حسابك.
`created_at`	تاريخ أو طابع زمني ISO	التُقط بواسطة Pubrio عند هذه اللحظة أو بعدها (UTC)، للمزامنة التزايدية.

تُخفي start_dates معظم الحملات النشطة للشركة، لأن الحملة التي انطلقت في مارس قد تكون لا تزال نشطة في أغسطس. استخدم active_dates ما لم ترد الإطلاقات تحديدًا.

مكان العرض

المفتاح	النوع	يطابق
`target_locations`	`string[]`	الدول التي عُرض فيها الإعلان. علاقة OR افتراضيًا؛ أضف `{"key": "target_locations", "operator": "and"}` إلى `filter_conditions` لاشتراط كل دولة.
`exclude_target_locations`	`string[]`	الدول المستبعدة.
`company_locations`	`string[]`	دولة مقر المُعلن.

الانتشار والحجم

المفتاح	النوع	يطابق
`reach_tiers`	`string[]`	نطاق انطباعات الإعلان: `lt_1k`، `1k_10k`، `10k_50k`، `50k_100k`، `100k_500k`، `500k_1m`، `1m_plus`. الإعلانات دون قيمة `total_impressions` لا تطابق أبدًا.
`advertisement_active_ads`، `advertisement_running_ads`، `advertisement_total_ads`، `advertisement_platform_count`، `advertisement_format_count`، `advertisement_impressions_estimate`	`[min, max]`	صفِّ الإعلانات حسب إجماليات المُعلن، مثل `advertisement_active_ads: [10, null]` التي تُعيد إعلانات من شركات لديها عشرة إعلانات نشطة على الأقل.
`advertisement_country_activity`	كائن	`{ "country": "US", "rank": [null, 100] }` — إعلانات من أكبر 100 مُعلن في تلك الدولة.

الإثراء

المفتاح	النوع	ملاحظات
`is_realtime_enrichment`	`boolean`	إن لم يُعد البحث شيئًا، اجمع البيانات من المصادر الآن وأعد البحث. لعمليات البحث المحدَّدة بشركة فقط.
`enrichment_mode`	`default` / `latest`	تعيد `latest` جمع البيانات في كل استدعاء بصرف النظر عن التخزين المؤقت.
`is_include_unlinked_companies`	`boolean`	أعِد أيضًا الإعلانات التي تعذّر على Pubrio ربطها بسجل شركة (`is_company_matched: false`).

التصفح والترتيب

تعمل per_page وpage وis_ascending_order كما في أي عملية بحث أخرى. تُرتَّب الصفوف حسب created_at (وقت الالتقاط)، الأحدث أولًا.

شكل الصف

{
  "advertisement_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
  "advertisement_search_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
  "created_at": "2026-09-01T02:00:07.068Z",
  "last_modified": "2026-09-01T02:00:07.068Z",
  "started_at": "2026-08-24T00:00:00.000Z",
  "ended_at": "2026-08-31T00:00:00.000Z",
  "title": "Your 2026 peak season prep checklist is here",
  "source_type": "linkedin",
  "advertisement_format": "Single Image Ad",
  "advertisement_format_normalized": "image",
  "is_company_matched": true,
  "advertiser": "Stripe",
  "advertiser_url": "https://www.linkedin.com/company/2135371",
  "advertisement_url": "https://www.linkedin.com/ad-library/detail/1518455034",
  "total_impressions": "< 1k",
  "total_impressions_lower": null,
  "total_impressions_upper": 1000,
  "image_url": "https://buckets.pubrio.com/images/public/….jpg",
  "video_url": null,
  "carousel_images": null,
  "destination_url": "https://stripe.com/industries/retail?trk=…",
  "raw_link_url": null,
  "target_country_codes": ["US"],
  "publisher_platforms": null,
  "companies": {
    "domain_search_id": "5378845d-7726-4817-aba9-ced8c5f41dee",
    "company_name": "Stripe",
    "domain": "stripe.com",
    "country_code": "US",
    "…": "…"
  }
}

تكون ended_at بقيمة null طالما الإعلان لا يزال نشطًا.
advertisement_format هو تصنيف المصدر الخاص؛ وadvertisement_format_normalized هو الاسم القياسي الذي يمكنك التصفية عليه.
destination_url هي صفحة الهبوط بعد إزالة التغليف؛ بينما تحتفظ raw_link_url برابط تتبّع النقر كما التُقط تمامًا.
total_impressions هو نص المصدر؛ والزوج _lower / _upper هو النطاق بعد تحليله.

`metadata` في هذه النقطة الطرفية

"metadata": {
  "profile": null,
  "filters": { "domains": ["stripe.com"], "source_types": ["tiktok", "bogus"], "per_page": 25, "language": "en" },
  "ignored_fields": [],
  "applied_source_types": ["tiktok"],
  "unsupported_source_types": ["bogus"],
  "coverage_notes": [{ "source_type": "tiktok", "scope": "eea_uk_ch" }]
}

المفتاح	متى يظهر	المعنى
`ignored_fields`	دائمًا	مفاتيح جسم الطلب التي تجاهلتها النقطة الطرفية
`applied_source_types`	عند إرسال `source_types`	القيم التي تم التعرّف عليها
`unsupported_source_types`	عند إرسال قيمة غير معروفة	القيم التي لم تطابق شيئًا
`coverage_notes`	عند الاقتضاء	ملاحظات التغطية للمصادر المطلوبة
`skipped_source_types`	عند الاقتضاء	`[{ "source_type", "reason" }]` — مصادر لم تُطبَّق بالنسبة لـ`target_locations` المطلوبة

وصفات جاهزة

محتوى إبداعي للمنافسين في سوق ما
إعلانات LinkedIn عالية الانتشار
إعلانات Meta على Instagram فقط

cURL

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["adyen.com", "checkout.com"],
    "target_locations": ["SG", "AU"],
    "advertisement_formats": ["video", "carousel"],
    "active_dates": ["2026-08-01", "2026-09-04"],
    "per_page": 25
  }'

cURL

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_locations": ["US"],
    "source_types": ["linkedin"],
    "reach_tiers": ["100k_500k", "500k_1m", "1m_plus"],
    "active_dates": ["2026-08-01", "2026-09-04"],
    "per_page": 25
  }'

كل companies.domain_search_id في الصفوف يمثّل شركة تنفق بكثافة على LinkedIn في الولايات المتحدة هذا الشهر.

cURL

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["nike.com"],
    "source_types": ["facebook"],
    "publisher_platforms": ["instagram"],
    "exclude_publisher_platforms": ["facebook"],
    "per_page": 25
  }'

صفحات ذات صلة

مرجع البحث في الإعلانات

كل معامل وحقل استجابة.

رؤى الإعلانات

الإجماليات وفئات الانتشار والمحتوى الإبداعي لشركة واحدة عبر فترة زمنية.

مرشحات النشاط الإعلاني

أوجد الشركات حسب نشاطها الإعلاني في البحث عن الشركات.

التعدادات والثوابت

المصادر والصيغ والمنصات وفئات الانتشار.

Monitor

البحث

المرشحات

الأشخاص

التوسع

متى تستخدمه

المصادر

التحديد بشركة

المرشحات

المصدر والصيغة

النص

التواريخ

مكان العرض

الانتشار والحجم

الإثراء

التصفح والترتيب

شكل الصف

`metadata` في هذه النقطة الطرفية

وصفات جاهزة

صفحات ذات صلة

مرجع البحث في الإعلانات

رؤى الإعلانات

مرشحات النشاط الإعلاني

التعدادات والثوابت

​متى تستخدمه

​المصادر

​التحديد بشركة

​المرشحات

​المصدر والصيغة

​النص

​التواريخ

​مكان العرض

​الانتشار والحجم

​الإثراء

​التصفح والترتيب

​شكل الصف

​metadata في هذه النقطة الطرفية

​وصفات جاهزة

​صفحات ذات صلة

مرجع البحث في الإعلانات

رؤى الإعلانات

مرشحات النشاط الإعلاني

التعدادات والثوابت

متى تستخدمه

المصادر

التحديد بشركة

المرشحات

المصدر والصيغة

النص

التواريخ

مكان العرض

الانتشار والحجم

الإثراء

التصفح والترتيب

شكل الصف

`metadata` في هذه النقطة الطرفية

وصفات جاهزة

صفحات ذات صلة