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

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

> اعثر على الإعلانات التي تديرها شركة عبر LinkedIn وMeta وGoogle وTikTok وApple — حسب المصدر والصيغة والدولة المستهدفة والانتشار والفترة النشطة — واقرأ بيانات الإبداع وصفحة الهبوط والانطباعات لكل منها.

يُعيد [البحث في الإعلانات](/ar/api-reference/endpoint/companies/advertisements_search) إعلانات فردية التقطها Pubrio، صفًا واحدًا لكل إعلان. يحمل كل صف الإبداع (العنوان، الصورة أو الفيديو، صفحة الهبوط)، ومكان عرضه، ووقت تشغيله، ونطاق الانطباعات الذي يبلّغ عنه المصدر.

```bash theme={null}
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_*` الشركات حسب حجم الإعلان دون رقم إنفاق فعلي.

للحصول على الإجماليات والاتجاهات استخدم [رؤى الإعلانات](/ar/api-reference/endpoint/companies/advertisements_insights). ولإيجاد *الشركات* حسب نشاطها الإعلاني بدلًا من الإعلانات نفسها، استخدم مرشحات `advertisement_*` في [البحث عن الشركات](/ar/api-reference/endpoint/companies/search).

## المصادر

| `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`. انظر [الصيغ](/ar/api-reference/enums#formats). |
| `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)، للمزامنة التزايدية.                                                                                                                                                                             |

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

### مكان العرض

| المفتاح                    | النوع      | يطابق                                                                                                                                           |
| -------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` (وقت الالتقاط)، الأحدث أولًا.

## شكل الصف

```json theme={null}
{
  "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` في هذه النقطة الطرفية

```json theme={null}
"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` المطلوبة |

## وصفات جاهزة

<Tabs>
  <Tab title="محتوى إبداعي للمنافسين في سوق ما">
    ```bash cURL theme={null}
    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
      }'
    ```
  </Tab>

  <Tab title="إعلانات LinkedIn عالية الانتشار">
    ```bash cURL theme={null}
    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 في الولايات المتحدة هذا الشهر.
  </Tab>

  <Tab title="إعلانات Meta على Instagram فقط">
    ```bash cURL theme={null}
    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
      }'
    ```
  </Tab>
</Tabs>

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

<CardGroup cols={2}>
  <Card title="مرجع البحث في الإعلانات" icon="code" href="/ar/api-reference/endpoint/companies/advertisements_search">
    كل معامل وحقل استجابة.
  </Card>

  <Card title="رؤى الإعلانات" icon="chart-column" href="/ar/api-reference/endpoint/companies/advertisements_insights">
    الإجماليات وفئات الانتشار والمحتوى الإبداعي لشركة واحدة عبر فترة زمنية.
  </Card>

  <Card title="مرشحات النشاط الإعلاني" icon="filter" href="/ar/developer-guides/filters/overview#مرشحات-النشاط-الإعلاني">
    أوجد الشركات حسب نشاطها الإعلاني في البحث عن الشركات.
  </Card>

  <Card title="التعدادات والثوابت" icon="list" href="/ar/api-reference/enums#advertisement-search">
    المصادر والصيغ والمنصات وفئات الانتشار.
  </Card>
</CardGroup>