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.
V1 Endpoint
This endpoint will be deprecated on May 6th, 2014. Please use the V2 endpoint.
V2 Endpoint
The following endpoint is used with HTTPS GET:
https://api.citygridmedia.com/bid/suggestion/v2
Request Parameters
| Name | Type | Description | Required | Valid values | Examples |
|---|---|---|---|---|---|
| what | String | Search term text | yes | Free form text | pizza |
| where | String | The geographic location | yes | A 5 digit zip code, a city-state pair or a geography name More information on geographies can be found here | 91011 |
| 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 | json |
Response
| 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 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 response | If no results are found then this value is null. |
ctr | Object | See below | |
estimated | Decimal | 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 (optimized search). 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. |
lowerBound | Decimal | Lower bound of the confidence interval | Based on the historical CTR and how many searches was used to compute it, we determine a confidence interval. It's computed for a 95% confidence. Meaning that we are sure at 95% that the CTR would be equal or higher that "lowerBound". |
upperBound | Decimal | Upper bound of the confidence interval | Based on the historical CTR and how many searches was used to compute it, we determine a confidence interval. It's computed for a 95% confidence. Meaning that we are sure at 95% that the CTR would be equal or less that "upperBound". |
generic | Boolean | Indicate if CTR was estimated using data from other publishers | When there is no historical data for a given search and publisher or if those data are not accurate enough we use data from other publishers in our network. While it allows us to provide data for new publishers or under terms and geographies never used before the CTR and confidence interval returned should be considered carefully as publishers can see slightly different CTR. |
Examples
No search result:
{
"listingCount": 0,
"totalBudget": null,
"cpc": null,
"ctr": null
}
No data for CTR:
{
"listingCount": 5,
"totalBudget": 141.96,
"cpc": 0.782,
"ctr": null
}
Result with CTR:
{
"listingCount": 6,
"totalBudget": 66,
"cpc": 1.248333,
"ctr": {
"estimated": 0.213,
"lowerBound": 0.188,
"upperBound": 0.238,
"generic": false
}
}
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 |