Reports

When and where one advertiser appeared, with the observation schedule

Returns one advertiser domain's history on the project's monitored searches in the window and filters: presence (checks with the advertiser / checks), first and last seen, active local days, the observation schedule (project frequency, checks, days with checks, longest wait between checks), weekly presence by local week, breakdowns by keyword, location, device and engine with the change between the two halves of the window, and returns (reappearances more than gap_days after the previous one, with checks in between that did not show it). Use the breakdowns to locate where an advertiser recurs and the returns section to review reappearances. Check the schedule and days with checks before treating a presence change as a trend; the rate describes saved checks, not all searches in the market. A change is null when either half has no checks. presence_rate = checks_with_advertiser / checks over saved monitoring checks, the same calculation as visibility in list_advertisers. It describes this sample, not impression share, spend, or proof that a keyword was bought. Hours or days without checks are not evidence of absence. Breakdown lists hold the 50 busiest rows each; *_total gives the full count. Imported studies are not included.

get/projects/{project_id}/advertisers/{domain}/history

Request

  • Base URL: https://adslighthouse.com/api/v1
  • URL: https://adslighthouse.com/api/v1/projects/{project_id}/advertisers/{domain}/history
  • 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.

domainstring required

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

Query parameters

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[]
keywordstring

Only checks of this exact keyword text, as list_keywords returns it.

gap_daysinteger

Minimum days away for a return: 3, 7, 14, 30.

Response

When and where one advertiser appeared, with the observation schedule

domainstring required
keywordstring nullable required
first_seenstring nullable required
last_seenstring nullable required
first_seen_any_datestring nullable required

Earliest saved check with the advertiser before the window end, same filters.

active_daysinteger required

Local days with at least one check showing it.

keywords_totalinteger required
markets_totalinteger required
request_idstring

Changes

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