Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

Expand
titleClick here for documentation on the V1 endpoint

The following endpoint is used with HTTPS GET:

Code Block
https://api.citygridmedia.com/bid/suggestion/v1

Request Parameters

NameTypeDescriptionRequiredValid valuesExamples
whatStringSearch term textyesFree form text

pizza
sporting goods
plumbers

whereStringThe geographic locationyesA 5 digit zip code, a city-state pair or a geography name
More information on geographies can be found here

91011
Pasadena, CA
Denver, CO Metro

publisherString

The publisher code that identifies you

yesContact your account manager for your publisher code 
formatStringFormat of the responseNoFor now only json is supported and is the defaultjson

 

Response

NameTypeDescriptionNotes
listingCount
IntegerNumber of listings returned in the first page of this searchIf there are no results then this field has the value 0. There is a maximum of 10 results per page
totalBudget
Decimal (currency)Total budget in US dollars that is currently available for the publisher and listings returned by this search

Budget is up to one hour stale.

Budget is not limited to the search term and geography queried and may be consumed by traffic to some other search term and geography. Additionally, budget may be shared across many listings. Budget should not be added across multiple search terms and geographies as this will provide an artificially high view of budget available.

Example: A single campaign may have $100 budget remaining for a restaurant listing and an insurance listing. A single search will only show one of these listings and both have $100 available. It's possible that $100 be spent entirely on one of the listings or evenly across both listings.

For a broader view on the budget available see the Bid Suggestion API. If no results are found then this value is null.

cpc

Decimal (currency)

The average CPC in US dollars for listings in this responseIf no results are found then this value is null.
ctr

Decimal
(percentage from 0 to 1)

The historical click-through-rate (CTR) for this search.

Seven-day historical CTR calculated as the number of clicks to advertiser profile pages divided by the number of times this search has been performed (organic search and optimized search). This field is null if no search has been made with same criteria.

Note this CTR is specific to the search term and geography irrespective of the listings currently available. Some listings may perform better than others but opportunity will change over time according to budget available and internal budget distribution.

Examples

No search result:

Code Block
languagejs
{
    "listingCount": 0,
    "totalBudget": null,
    "cpc": null,
    "ctr": null
}

No historical data for CTR:

Code Block
languagejs
{
    "listingCount": 10,
    "totalBudget": 972.6,
    "cpc": 0.6,
    "ctr": null
}

Result with CTR

Code Block
languagejs
{
    "listingCount": 10,
    "totalBudget": 424.8,
    "cpc": 0.55,
    "ctr": 0.19
}

...

NameTypeDescriptionRequiredValid valuesExamples
whatStringSearch term textyesFree form text

pizza
sporting goods
plumbers

whereStringThe geographic locationyesA 5 digit zip code, a city-state pair or a geography name
More information on geographies can be found here

91011
Pasadena, CA
Denver, CO Metro

publisherString

The publisher code that identifies you

yesContact your account manager for your publisher code 
formatStringFormat of the responseNoFor now only json is supported and is the defaultjson

...