Bid Suggestion API

Introduction

The Bid Suggestion API allows publishers to evaluate the opportunity associated with CityGrid's Optimized Search Result Page (OSRP) in order to make informed decisions in how they buy traffic. Given a search term and location the Bid Suggestion API will provide insight into the number of paid listings and the cumulative budget available, average CPC and average click-through-rate for the listings. Given this information a publisher can compare the eCPM of a search term within a specific location to the cost to buy that traffic.

HTTPS Endpoint

The following endpoint is used with HTTPS GET:

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

Request Parameter

Request Headers

Name	Description	Required	Valid values
Accept	Specify on which format the client wants to get the response. This can also be specified in url parameter.	No	Application/json

URL Parameters

Name	Type	Description	Required	Valid values	Examples
what	String	Search term text	yes	Free form text	pizza sporting goods plumbers
where	String	The geographic location	yes	A market, city-state, 5 digit zip code, or neighborhood. For a list of our supported geographies please refer to Content by CityGrid	91011 Denver, CO Metro Pasadena, CA
publisher	String	The publisher code that identifies you	yes	Contact your account manager for your publisher code
format	String	Format of the response	No	For now only json is supported and is the default. This value overrides the one in 'Accept' header if they are both present	json

Response

Response fields

Name	Type	Description	Notes
listingCount	Integer	Number of listings returned in the first page of this search	If 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 Budget API. If no results are found then this value is null.
cpc	Decimal (currency)	The average CPC in US dollars for listings in this response	If 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:

{
    "listingCount": 0,
    "totalBudget": null,
    "cpc": null,
    "ctr": null
}

No historical data for CTR:

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

Result with CTR

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

Error Handling

Bid API follows REST philosophy for error handling, meaning that meaningful Http Response Codes are returned. Additionally For all status different than 200 it provides a standardized error response:

Name	Description
errorCode	The error code associated to the error. It's the same as the Http Response Code
message	Message describing the error

Example:

{
    "errorCode": 400,
    "message": "Required String parameter 'pub' is not present"
}

Response Codes

Code	Description	Scenario	Notes
200	OK	Request was successful	If some data are missing (e.g ctr not available) return code is 200 so you should support the case when some fields are null
400	Bad Request	Request is synthetically incorrect (e.g required field is missing)	The 'message' field contains the exact cause of the issue (e.g Required String parameter 'pub' is not present)
422	Unprocessable Entity	The 'where' parameter is not translatable to a searchable area
500	Internal Server Error	An unexpected error occurred on server side
504	Gateway Timeout	Server is up but request can't be fulfilled because of some failure within our system	Client could retry the request as the most likely cause is a timeout inside our system