# SearchAPI

> Access ad transparency data from Google, Meta, TikTok, Reddit, and LinkedIn ad libraries.

Source: https://cotera.co/docs/reference/tools/individual-tools/search-api

---

**Authentication Type:** API Key
**Description:** Access ad transparency data from Google, Meta, TikTok, Reddit, and LinkedIn ad libraries.

***

## Authentication

To authenticate, you'll need a SearchAPI key from [searchapi.io](https://www.searchapi.io/).

***

## Google Web Search

### Google Search

Perform a Google web search and retrieve organic results, knowledge panels, and related searches.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (required): Search query
* **location** `string` (nullable): Geographic location for localized results
* **gl** `string` (nullable): Country code for Google domain (e.g., "us", "uk")
* **hl** `string` (nullable): Language code for results (e.g., "en")
* **num** `number` (nullable): Number of results to return (default: 10, max: 100)
* **page** `number` (nullable): Page number for pagination
* **time\_period** `string` (nullable): Time filter: "last\_hour", "last\_day", "last\_week", "last\_month", "last\_year"

**Returns:**

* **organic\_results** `array of objects`: Organic search results
  * **position** `number`: Result ranking position
  * **title** `string`: Page title
  * **link** `string`: URL
  * **snippet** `string` (nullable): Result snippet/description
  * **displayed\_link** `string` (nullable): Displayed URL
* **knowledge\_graph** `object` (nullable): Knowledge panel data
* **related\_searches** `array of objects` (nullable): Related search suggestions
* **total\_results** `number` (nullable): Estimated total results

**Example Usage:**

```json
{
  "q": "best project management tools 2024",
  "num": 20,
  "gl": "us"
}
```

***

## Google Ads Transparency Center

Search and analyze ads from the Google Ads Transparency Center.

### Google Ads Advertiser Search

Search for advertisers and domains in the Google Ads Transparency Center. Use this to find advertiser IDs before using other Google Ads tools.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (required): Search keyword for advertisers/domains
* **region** `string` (nullable): Geographic filter (default: "anywhere")
* **numAdvertisers** `number` (nullable): Results count (default: 10, max: 100)
* **numDomains** `number` (nullable): Results count (default: 10, max: 100)

**Returns:**

* **advertisers** `array of objects`: List of matching advertisers
  * **id** `string`: Advertiser ID - use for google-ads-search and google-ads-ad-details
  * **name** `string`: Advertiser name
  * **region** `string` (nullable): Advertiser region
  * **adsCount** `object` (nullable): Range of ad count
    * **lower** `number`: Lower bound
    * **upper** `number`: Upper bound
  * **isVerified** `boolean` (nullable): Whether the advertiser is verified
* **domains** `array of objects`: List of matching domains
  * **name** `string`: Domain name

**Example Usage:**

```json
{
  "q": "Tesla"
}
```

### Google Ads Search

Search for ads in the Google Ads Transparency Center by advertiser ID or domain. Returns ad creatives with their IDs for detailed lookup.

**Operation Type:** Query (Read)

**Parameters:**

* **advertiserId** `string` (nullable): Advertiser ID (starts with "AR"). Either this or domain is required.
* **domain** `string` (nullable): Domain to search (e.g., "tesla.com"). Either this or advertiserId is required.
* **region** `string` (nullable): Geographic filter
* **platform** `string` (nullable): Platform filter: google\_play, google\_maps, google\_search, youtube, google\_shopping
* **adFormat** `string` (nullable): Ad format filter: text, image, video
* **timePeriod** `string` (nullable): Time period: today, yesterday, last\_7\_days, last\_30\_days, or YYYY-MM-DD..YYYY-MM-DD
* **num** `number` (nullable): Results per page (default: 40, max: 100)
* **nextPageToken** `string` (nullable): Pagination token from previous response

**Returns:**

* **adCreatives** `array of objects`: List of ad creatives
  * **id** `string`: Creative ID - use as creative\_id for google-ads-ad-details
  * **position** `number` (nullable): Ranking position
  * **advertiser** `object`: Advertiser info
    * **id** `string`: Advertiser ID
    * **name** `string` (nullable): Advertiser name
  * **format** `string` (nullable): Ad format: video, image, text
  * **targetDomain** `string` (nullable): Target domain
  * **firstShownDatetime** `string` (nullable): First shown timestamp
  * **lastShownDatetime** `string` (nullable): Last shown timestamp
  * **totalDaysShown** `number` (nullable): Total days the ad was shown
* **totalResults** `number` (nullable): Total number of results
* **nextPageToken** `string` (nullable): Token for next page, null if no more pages

**Example Usage:**

```json
{
  "domain": "tesla.com",
  "timePeriod": "last_30_days"
}
```

### Google Ads Ad Details

Get detailed information about a specific Google ad including targeting, impressions, and creative variations.

**Operation Type:** Query (Read)

**Parameters:**

* **advertiserId** `string` (required): Advertiser ID (starts with "AR")
* **creativeId** `string` (required): Creative ID (starts with "CR") - get from google-ads-search results

**Returns:**

* **adInformation** `object` (nullable): Ad information
  * **format** `string` (nullable): Ad format: video, image, text
  * **topic** `string` (nullable): Ad topic/category
  * **firstShownDate** `string` (nullable): First shown date
  * **lastShownDate** `string` (nullable): Last shown date
  * **lastShownDatetime** `string` (nullable): Last shown timestamp
  * **impressionsDataAvailableFrom** `string` (nullable): When impression data became available
  * **regions** `array of objects` (nullable): Regional impression data
    * **region** `string`: Region name
    * **impressions** `object` (nullable): Impression range
      * **lower** `number` (nullable): Lower bound
      * **upper** `number` (nullable): Upper bound
    * **platform** `string` (nullable): Platform
  * **audienceSelection** `object` (nullable): Audience targeting details
    * **age** `string` (nullable): Age targeting
    * **gender** `string` (nullable): Gender targeting
    * **location** `string` (nullable): Location targeting
* **variations** `array of objects` (nullable): Ad creative variations
  * **format** `string` (nullable): Variation format
  * **title** `string` (nullable): Ad title
  * **description** `string` (nullable): Ad description
  * **link** `string` (nullable): Destination link
  * **thumbnail** `string` (nullable): Thumbnail URL
  * **videoUrl** `string` (nullable): Video URL
  * **imageUrl** `string` (nullable): Image URL

**Example Usage:**

```json
{
  "advertiserId": "AR12345678901234567",
  "creativeId": "CR12345678901234567"
}
```

***

## Meta Ad Library

Search and analyze ads from the Meta (Facebook/Instagram) Ad Library.

### Meta Ads Page Search

Search for pages and advertisers in the Meta Ad Library. Returns page IDs for use with meta-ads-ad-details.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (required): Search keyword for pages/advertisers
* **country** `string` (nullable): Country code filter (default: "ALL")
* **adType** `string` (nullable): Ad type: all, political\_and\_issue\_ads, housing\_ads, employment\_ads, credit\_ads

**Returns:**

* **pageResults** `array of objects`: List of matching pages
  * **pageId** `string`: Page ID - use for meta-ads-ad-details
  * **name** `string`: Page name
  * **category** `string` (nullable): Page category
  * **likes** `number` (nullable): Page likes
  * **verification** `string` (nullable): Verification status
  * **entityType** `string` (nullable): Entity type
  * **imageUri** `string` (nullable): Profile image URL
  * **igUsername** `string` (nullable): Instagram username
  * **igFollowers** `number` (nullable): Instagram followers
  * **pageAlias** `string` (nullable): Page URL alias
* **locationResults** `array of objects` (nullable): Location results
  * **id** `string`: Location ID
  * **name** `string`: Location name
  * **locationType** `string` (nullable): Location type
  * **imageUri** `string` (nullable): Image URL
* **keywordResults** `array of strings` (nullable): Keyword autocomplete suggestions

**Example Usage:**

```json
{
  "q": "Nike"
}
```

### Meta Ads Search

Search for ads in the Meta Ad Library by keyword or page ID. Returns ad creatives, copy, and targeting.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (nullable): Search keyword. Either q or pageId is required.
* **pageId** `string` (nullable): Page ID to filter ads from specific advertiser. Get from meta-ads-page-search.
* **country** `string` (nullable): Country code filter (default: "ALL")
* **adType** `string` (nullable): Ad type: all, political\_and\_issue\_ads, housing\_ads, employment\_ads, credit\_ads
* **activeStatus** `string` (nullable): Filter by status: active, inactive, all
* **mediaType** `string` (nullable): Media type: all, video, image, meme, image\_and\_meme, none
* **platforms** `string` (nullable): Platforms filter (comma-separated): facebook, instagram, audience\_network, messenger, threads
* **startDate** `string` (nullable): Start date filter (YYYY-MM-DD)
* **endDate** `string` (nullable): End date filter (YYYY-MM-DD)
* **sortBy** `string` (nullable): Sort order: most\_recent, impressions\_high\_to\_low
* **nextPageToken** `string` (nullable): Pagination token from previous response

**Returns:**

* **ads** `array of objects`: List of ads
  * **adArchiveId** `string`: Ad archive ID - use for meta-ads-ad-details
  * **pageId** `string` (nullable): Advertiser page ID
  * **pageName** `string` (nullable): Advertiser name
  * **isActive** `boolean` (nullable): Whether ad is currently active
  * **startDate** `string` (nullable): Ad start date
  * **endDate** `string` (nullable): Ad end date
  * **totalActiveTime** `number` (nullable): Total active time in seconds
  * **publisherPlatforms** `array of strings` (nullable): Platforms where ad is shown
  * **snapshot** `object` (nullable): Ad creative snapshot
    * **bodyText** `string` (nullable): Ad body text/copy
    * **ctaText** `string` (nullable): Call to action text
    * **ctaType** `string` (nullable): CTA type
    * **linkUrl** `string` (nullable): Destination URL
    * **displayFormat** `string` (nullable): Display format (CAROUSEL, etc)
    * **images** `array of objects` (nullable): Ad images
      * **originalImageUrl** `string` (nullable): Original full-resolution image URL
      * **resizedImageUrl** `string` (nullable): Resized/optimized image URL
    * **cards** `array of objects` (nullable): Carousel cards
      * **title** `string` (nullable): Card title
      * **body** `string` (nullable): Card body
      * **linkUrl** `string` (nullable): Card link URL
      * **originalImageUrl** `string` (nullable): Original card image URL
      * **resizedImageUrl** `string` (nullable): Resized card image URL
    * **pageProfilePictureUrl** `string` (nullable): Page profile picture
    * **pageLikeCount** `number` (nullable): Page like count
* **nextPageToken** `string` (nullable): Token for next page, null if no more pages

**Example Usage:**

```json
{
  "pageId": "123456789",
  "activeStatus": "active",
  "mediaType": "video"
}
```

### Meta Ads Ad Details

Get detailed information about a Meta ad including targeting, reach, and political ad insights.

**Operation Type:** Query (Read)

**Parameters:**

* **adArchiveId** `string` (required): Ad archive ID - find this in Meta Ad Library URLs
* **isPolitical** `boolean` (nullable): Set to true for political ads to get demographic breakdowns
* **country** `string` (nullable): Country code for transparency data (requires pageId)
* **pageId** `string` (nullable): Page ID - required when country is specified

**Returns:**

* **adArchiveId** `string`: Ad archive ID
* **aaaInfo** `object` (nullable): AAA targeting/audience info
  * **targeting** `object` (nullable): Targeting information
  * **audience** `object` (nullable): Audience information
* **transparencyByLocation** `array of objects` (nullable): Transparency data by location
  * **location** `string`: Location name
  * **reach** `number` (nullable): Reach count
  * **impressions** `number` (nullable): Impressions count
* **insights** `object` (nullable): Political ad insights
  * **ageAudience** `object` (nullable): Age demographic breakdown
  * **genderAudience** `object` (nullable): Gender demographic breakdown
  * **locationAudience** `object` (nullable): Location demographic breakdown
  * **totalReach** `number` (nullable): Total reach
  * **euTotalReach** `number` (nullable): EU total reach
  * **spend** `object` (nullable): Spend information
    * **lower** `number` (nullable): Lower spend bound
    * **upper** `number` (nullable): Upper spend bound
    * **currency** `string` (nullable): Currency
* **payerBeneficiaryData** `object` (nullable): Payer/beneficiary information
  * **payer** `string` (nullable): Payer name
  * **beneficiary** `string` (nullable): Beneficiary name

**Example Usage:**

```json
{
  "adArchiveId": "123456789012345",
  "isPolitical": true
}
```

***

## Reddit Ad Library

Search ads from the Reddit Ad Library.

### Reddit Ads

Search the Reddit Ad Library for ads by keyword, industry, budget, or objective type.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (nullable): Search terms
* **industry** `string` (nullable): Industry filter: EDUCATION, TECH\_B2C, TECH\_B2B, RETAIL\_AND\_ECOMMERCE, ENTERTAINMENT, GAMING, FINANCIAL\_SERVICES, HEALTH\_AND\_BEAUTY, CONSUMER\_PACKAGED\_GOODS, EMPLOYMENT, AUTO, TRAVEL, REAL\_ESTATE, GAMBLING\_AND\_FANTASY\_SPORTS, POLITICS\_AND\_GOVERNMENT, OTHER
* **budgetCategory** `string` (nullable): Budget tier: LOW, MEDIUM, HIGH
* **postType** `string` (nullable): Ad format: VIDEO, IMAGE, CAROUSEL, FREE\_FORM
* **placements** `string` (nullable): Ad placement: COMMENTS\_PAGE, FEED
* **objectiveType** `string` (nullable): Campaign objective: CLICKS, IMPRESSIONS, CONVERSIONS, VIDEO\_VIEWABLE\_IMPRESSIONS, APP\_INSTALLS

**Returns:**

* **ads** `array of objects`: List of ads
  * **id** `string`: Ad ID
  * **budgetCategory** `string` (nullable): Budget tier
  * **industry** `string` (nullable): Industry classification
  * **placements** `array of strings` (nullable): Where ad appears
  * **objectiveType** `string` (nullable): Campaign objective
  * **creative** `object` (nullable): Creative content
    * **headline** `string` (nullable): Ad headline
    * **body** `string` (nullable): Ad body text
    * **thumbnailUrl** `string` (nullable): Thumbnail URL
    * **videoUrl** `string` (nullable): Video URL
    * **destinationUrl** `string` (nullable): Click destination
  * **profile** `object` (nullable): Advertiser profile
    * **name** `string` (nullable): Advertiser name
    * **avatarUrl** `string` (nullable): Advertiser avatar
  * **createdAt** `string` (nullable): Creation timestamp

**Example Usage:**

```json
{
  "industry": "TECH_B2B",
  "budgetCategory": "HIGH"
}
```

***

## TikTok Ads Library

Search and analyze ads from the TikTok Ads Library.

### TikTok Ads Advertiser Search

Search for advertisers in the TikTok Ads Library. Returns advertiser IDs for use with tiktok-ads-search.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (required): Advertiser name to search

**Returns:**

* **advertisers** `array of objects`: List of matching advertisers
  * **id** `string`: Advertiser ID - use for tiktok-ads-search
  * **name** `string`: Advertiser name
* **keywordResults** `array of strings` (nullable): Related keyword suggestions

**Example Usage:**

```json
{
  "q": "Shopify"
}
```

### TikTok Ads Search

Search for ads in the TikTok Ads Library by keyword, advertiser, country, or time period.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (nullable): Search keyword
* **advertiserId** `string` (nullable): Filter to specific advertiser - get from tiktok-ads-advertiser-search
* **country** `string` (nullable): Country code filter (default: "ALL")
* **timePeriod** `string` (nullable): Date range: YYYY-MM-DD..YYYY-MM-DD
* **sortBy** `string` (nullable): Sort order: last\_shown\_date\_newest\_to\_oldest, last\_shown\_date\_oldest\_to\_newest, published\_date\_newest\_to\_oldest, published\_date\_oldest\_to\_newest, unique\_users\_seen\_low\_to\_high, unique\_users\_seen\_high\_to\_low
* **nextPageToken** `string` (nullable): Pagination token from previous response

**Returns:**

* **ads** `array of objects`: List of ads
  * **id** `string`: Ad ID
  * **position** `number` (nullable): Ranking position
  * **advertiser** `string` (nullable): Advertiser name
  * **firstShownDatetime** `string` (nullable): First shown timestamp
  * **lastShownDatetime** `string` (nullable): Last shown timestamp
  * **videoLink** `string` (nullable): Video URL
  * **coverImage** `string` (nullable): Thumbnail URL
  * **estimatedAudience** `string` (nullable): Audience range as string
  * **estimatedAudienceMin** `number` (nullable): Minimum audience estimate
  * **estimatedAudienceMax** `number` (nullable): Maximum audience estimate
* **totalResults** `number` (nullable): Total number of results
* **nextPageToken** `string` (nullable): Token for next page

**Example Usage:**

```json
{
  "q": "fitness app",
  "sortBy": "unique_users_seen_high_to_low"
}
```

***

## LinkedIn Ad Library

Search ads from the LinkedIn Ad Library.

### LinkedIn Ads

Search the LinkedIn Ad Library for ads by keyword, advertiser, country, or time period.

**Operation Type:** Query (Read)

**Parameters:**

* **q** `string` (nullable): Search keyword
* **advertiser** `string` (nullable): Advertiser name/company filter
* **country** `string` (nullable): Country codes, comma-separated (e.g., "US,CA,GB")
* **timePeriod** `string` (nullable): Time period: last\_year, this\_year, this\_month, last\_30\_days, or YYYY-MM-DD..YYYY-MM-DD
* **nextPageToken** `string` (nullable): Pagination token from previous response

**Returns:**

* **ads** `array of objects`: List of ads
  * **id** `string`: Ad ID
  * **position** `number` (nullable): Ranking position
  * **advertiser** `object` (nullable): Advertiser info
    * **name** `string` (nullable): Advertiser name
    * **thumbnail** `string` (nullable): Logo URL
  * **adType** `string` (nullable): Ad type: image, event, document, carousel
  * **content** `object` (nullable): Ad content
    * **headline** `string` (nullable): Ad headline
    * **ctaText** `string` (nullable): Call to action text
    * **images** `array of strings` (nullable): Image URLs
    * **pages** `array of objects` (nullable): Document/carousel pages
      * **image** `string` (nullable): Page image URL
      * **text** `string` (nullable): Page text
  * **link** `string` (nullable): LinkedIn ad detail URL
* **totalResults** `number` (nullable): Total number of results
* **nextPageToken** `string` (nullable): Token for next page

**Example Usage:**

```json
{
  "advertiser": "Salesforce",
  "timePeriod": "last_30_days"
}
```

***

## Common Use Cases

**Competitive Intelligence:**

* Monitor competitor ad campaigns across multiple platforms
* Analyze messaging, targeting, and creative strategies
* Track when competitors run ads and estimate their reach/spend

**Market Research:**

* Study ad trends in specific industries
* Identify top advertisers by platform
* Research political and issue advertising

**Brand Monitoring:**

* Track unauthorized use of your brand in ads
* Monitor how partners and affiliates represent your brand
* Verify compliance with brand guidelines across ad networks