Projects

Forecast the monthly checks and allowance for a proposed change

Previews, without saving anything, whether a proposed configuration fits the account's plan, with the same calculation the New project, Edit monitoring plan and Add keywords forms and the server use. Compare the proposed keyword, location, device and search-engine coverage with the account's full-month check allowance before choosing a monitoring plan. change=new_project needs country and keywords (other fields default as in create_project); change=update_project needs project_id plus the fields to change, as in update_project; change=add_keywords needs project_id and keywords (country and language default to the project's). One check is one search: keyword × location × device × source (Google, Bing, Shopping); a project that checks only some of its locations per run counts locations_per_run. scheduled_checks.full_month is account-wide for a 31-day month; the plan must cover both it and projected_this_month. Periods are UTC months. Use it to explain projected check usage and plan fit before calling create_project, update_project or add_keywords.

post/check-demand

Request

  • Base URL: https://adslighthouse.com/api/v1
  • URL: https://adslighthouse.com/api/v1/check-demand
  • Auth: HTTP bearer

Request body

change'new_project' | 'update_project' | 'add_keywords' required

What to preview.

project_idstring

Required for update_project and add_keywords.

namestring

Project name, such as Nike US.

countrystring

Market, ISO 3166-1 alpha-2 such as US. Changing it without locations monitors the whole new country.

languagestring

Search language, such as en.

locations_per_runinteger nullable

How many of the listed locations each run checks, least recently checked first, so the whole list is covered over time. null, or a number at or above the list size, checks every location in every run. Counts against the plan's locations_per_project and the check forecast. Omit to keep the current value.

randomize_check_timesboolean

Start each scheduled run at a random moment inside its interval (for Every hour, once in each UTC hour). It never runs more often than the fixed schedule and uses the same checks. Omit to keep the current value.

devicesstring[]

The full list of devices to check.

search_enginesstring[]

The full list of search engines. May be empty only when shopping_enabled is true. The market must offer each engine (get_monitoring_options).

shopping_enabledboolean

Also check Google Shopping ads. Needs a plan that includes Shopping and a market with Google.

monitoring_frequency'manual' | 'daily' | 'twice_daily' | 'four_times_daily' | 'six_times_daily' | 'twelve_times_daily' | 'hourly' | 'every_30_minutes' | 'every_15_minutes'

How often scheduled checks run, from daily to every_15_minutes. manual pauses scheduled monitoring (on-demand checks still work); any other value resumes it. The plan limits the most frequent schedule (allowed_on_plan in get_monitoring_options), and the account's full-month forecast must fit its scheduled check allowance.

keywordsstring[]

Search terms, up to 20, such as nike running shoes.

Response

Forecast the monthly checks and allowance for a proposed change

fitsboolean required

True when the account's plan can carry the change: projects, keywords, full-month scheduled checks and any first run.

blocked_reasonstring nullable required

Why it does not fit, as the app would say it; null when it fits.

periodstring required

Usage month, YYYY-MM in UTC.

first_run_checksinteger required

On-demand checks a new project's first run would use (keywords × locations checked per run × devices × sources). 0 for other changes.

realtime_remaininginteger required

On-demand checks left this month.

request_idstring

Changes

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