Keywords

Advertisers or distinct ads seen for one keyword

Lists what one keyword's saved checks found in the window and filters, 10 per page, grouped like the keyword page. view=advertisers (default): one row per advertiser domain. view=ads: one row per distinct ad (same domain, copy, display URL and full destination URL), with the ad copy, where it was seen first and last, and its automated policy review when there is one. ads_observed counts occurrences; checks_with_ads counts saved checks where the row appeared; best_position is the highest paid slot reached (1 is first). These are observations of search results, not competitor spend or proof of a policy violation. Sorts: most-observed (default), newest, oldest, name (advertisers only), top-position or lowest-position (ads only). advertiser narrows view=ads to one domain.

get/projects/{project_id}/keywords/{keyword_id}/ads

Request

  • Base URL: https://adslighthouse.com/api/v1
  • URL: https://adslighthouse.com/api/v1/projects/{project_id}/keywords/{keyword_id}/ads
  • Auth: HTTP bearer

Path parameters

project_idstring required

The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.

keyword_idstring required

The keyword id from list_keywords.

Query parameters

view'advertisers' | 'ads'
sort'most-observed' | 'newest' | 'oldest' | 'name' | 'top-position' | 'lowest-position'
advertiserstring

Advertiser domain as it appears in list_advertisers, such as rival.example.

range'7d' | '14d' | '30d' | '12m' | 'custom'

Window ending today: 7d, 14d, 30d (default) or 12m. Use custom with from and to for fixed dates.

fromstring

First local day, YYYY-MM-DD (custom range).

tostring

Last local day, YYYY-MM-DD, included in full (custom range).

time_zonestring

IANA time zone for day boundaries, such as America/New_York. Defaults to the time zone of the person the credential acts for.

'google' | 'bing'
OR
string[]
'desktop' | 'mobile'
OR
string[]
'windows' | 'macos' | 'android' | 'ios' | 'unspecified'
OR
string[]
string
OR
string[]
string
OR
string[]
cursorstring

The next_cursor value from the previous page. Omit it for the first page.

Response

Advertisers or distinct ads seen for one keyword

view'advertisers' | 'ads' required
sort'most-observed' | 'newest' | 'oldest' | 'name' | 'top-position' | 'lowest-position' required
totalinteger required

Rows in the whole selection, before paging.

next_cursorstring nullable required

Pass as cursor to get the next page; null on the last page.

request_idstring

Changes

No recorded changes to this operation across all 1 revision of this API.