Budget API
Introduction
The CityGrid Budget API allows publishers to discover the advertisers with budget available to them in the network and check the available remaining budget of a particular advertiser. Publishers who wish to check budgets must use this API so their quality score is unaffected by too many queries without subsequent clicks or user actions.
Contents
Discovering Opportunities
The budget API allows publishers to discover what advertisers have budget available at a particular moment in time by making accessible a report, generated on demand of the advertisers and budgets available.
HTTP Endpoint
The following endpoint is used with HTTP GET:
Request Parameter
The following query string parameters are used with the Budget API endpoint:
Parameter | Description | Required | Valid Values | Examples |
---|---|---|---|---|
publisher | The publisher code that identifies you. This parameter is required so that we can reflect the accurate budget. | Yes | Contact your account manager for your publisher code. | acme |
format | The desired format for the result. Default is xml. | No | json, xml | xml |
includeBudgetId | This parameter decides if a budget allocation Id would show in the result. Default is false. | No | true, false | true |
Response
We use streaming instead of pagination for the response given that the result could be quite large. The response is a streaming-octet content type, which is a file with the result in XML or JSON based on the format specified in the request.
The table below describes the content of the response file. We also included an example of how to write a client to retrieve the response file using this method
Element | Parent Element | Attributes | Description |
---|---|---|---|
ads |
|
| Top level container of advertisement elements |
ad | ads |
| Advertisement data |
listings | ad |
| The group of businesses sharing the same budget |
listing | listings |
| Data of a business location |
listing_id | listing |
| The ID to uniquely identify CityGrid's businesses |
listing_name | listing |
| The name of the business |
reference_id | listing | The ID to uniquely identify provider to which listing belongs to | |
categories | listing |
| List of categories associated to this advertiser |
category | categories | primary= true if the category is primary for this business | Category associated to this advertiser |
markets | listing |
| List of markets associated to this advertiser |
market | markets |
| Market associated to this advertiser |
neighborhoods | listing |
| List of neighborhoods associated to this advertiser |
neighborhood | neighborhood |
| Neighborhood associated to this advertiser |
cities | listing | List of cities associated to this advertiser | |
city | cities | City associated to this advertiser | |
postal_codes | listing | List of postal codes associated to this advertiser | |
postal_code | postal_codes | Postal code associated to this advertiser | |
ppe | ad |
| Price per event |
remaining_budget | ad |
| Budget available |
budget_allocation_id (optional) | ad | Budget allocation id available |
Header Values
Parameter | Description | Required | Valid Values |
---|---|---|---|
Content-Type | Return format | Yes | application/octet-stream |
XML Output
In the case of an XML, the file downloaded will look like the following:
<ads> <ad> <ppe>1.0</ppe> <remaining_budget>31.0</remaining_budget> <listings> <listing> <listing_id>1111</listing_id> <listing_name>XYZ Inc</listing_name> <reference_id>1</reference_id> <categories> <category>Overnight Shipping</category> <category>Commercial Shipping</category> </categories> <markets> <market>Cape Coral-Fort Myers, FL</market> <market>Naples-Marco Island, FL</market> </markets> <neighborhoods> <neighborhood>North Naples</neighborhood> <neighborhood>Urban Estates</neighborhood> </neighborhoods> <cities> <city>Los Angeles</city> <city>San Diego</city> </cities> <postal_codes> <postal_code>99999</postal_code> <postal_code>11111</postal_code> </postal_codes> </listing> <listing> <listing_id>3333</listing_id> <listing_name>abc Inc</listing_name> <reference_id>1</reference_id> <categories> <category primary="true">Attorneys</category> <category>Wrongful Death Attorneys</category> </categories> <markets> <market>West Palm Beach-Boca Raton-Boynton Beach, FL</market> <market>Ocala, FL</market> </markets> <neighborhoods> <neighborhood>Water Catchment Area</neighborhood> <neighborhood>Golden Lakes</neighborhood> </neighborhoods> <cities/> <postal_codes/> </listing> </listings> </ad> <ad> <ppe>2.0</ppe> <remaining_budget>32.0</remaining_budget> <listings> <listing> <listing_id>2222</listing_id> <listing_name>stores Inc</listing_name> <reference_id>1</reference_id> <categories> <category>Overnight Shipping</category> <category>Commercial Shipping</category> </categories> <markets> <market>Cape Coral-Fort Myers, FL</market> <market>Naples-Marco Island, FL</market> </markets> <neighborhoods> <neighborhood>North Naples</neighborhood> <neighborhood>Urban Estates</neighborhood> </neighborhoods> <cities/> <postal_codes/> </listing> <listing> <listing_id>4444</listing_id> <listing_name>ZZZ Inc</listing_name> <reference_id>1</reference_id> <categories> <category primary="true">Attorneys</category> <category>Wrongful Death Attorneys</category> </categories> <markets> <market>West Palm Beach-Boca Raton-Boynton Beach, FL</market> <market>Ocala, FL</market> </markets> <neighborhoods> <neighborhood>Water Catchment Area</neighborhood> <neighborhood>Golden Lakes</neighborhood> </neighborhoods> <cities> <city>Los Angeles</city> <city>San Diego</city> </cities> <postal_codes> <postal_code>99999</postal_code> <postal_code>11111</postal_code> </postal_codes> </listing> </listings> </ad> </ads>
XML Output with parameter includeBudgetId
In the case of an XML, the file downloaded will look like the following:
<ads> <ad> <ppe>0.2</ppe> <remaining_budget>3.0311</remaining_budget> <budget_allocation_id>16369425</budget_allocation_id> <listings> <listing> <listing_id>838628150</listing_id> <listing_name>Mojo's Seafood & Chicken</listing_name> <reference_id>7</reference_id> <categories> <category>Catering</category> <category>Health Food</category> <category>Home Meal Delivery</category> <category>Restaurants</category> <category primary="true">Seafood Markets</category> </categories> <markets/> <neighborhoods/> <postal_codes> <postal_code>36542</postal_code> </postal_codes> <cities> <city>Gulf Shores</city> </cities> </listing> </listings> </ad> </ads>
Connecting to the streaming Discovery API
Accessing this API requires keeping a persistent HTTP connection open. This involves thinking about your client application differently than if you are using a REST API. In other words, use this API as a separate process independent of user requests.
Connecting
To connect to the Discovery API, form an HTTP request and download the response file. You must keep the connection open while you are downloading the file. This may be different for every language or framework.
We provide a simple client example to open a connection and download the response file
Client: (Using HttpClient, Framework independent) String endpoint = " http://stream.api.citygridmedia.com/ads/budget/v2/discover?publisher=test&format=xml"; HttpGet httpGet = new HttpGet(endpoint); HttpClient client = new DefaultHttpClient(); HttpContext context = new BasicHttpContext(); HttpResponse getResponse = client.execute(httpGet, context); if (getResponse.getStatusLine().getStatusCode() == HttpStatus.SC_OK) { int size = -1; OutputStream os = new FileOutputStream("result.xml"); InputStream is = getResponse.getEntity().getContent(); byte[] buffer = new byte[4096]; while ((size = is.read(buffer)) != -1) { os.write(buffer, 0, size); } os.flush(); os.close(); client.getConnectionManager().shutdown(); }
Disconnecting
We will maintain the connection open until you close it but in some cases we may close your connection:
- Too many connections are open for the same publisher code. There is no need to download the files multiple times in parallel since the result will be the same.
- A client stops reading data suddenly. This probably means your connection got lost so we will close it for you
- A server is restarted. This may happen in the case of a new release that needs system down time, but they are not frequent
Rate limits
We are not enforcing hard limits on this version of the API, but we ask that you don’t try to connect to this API over 5 times per day.
Checking Budget Available
The budget API also allows publishers to check what is the advertisers' budget available to them based on their traffic quality.
Obtaining Budget Available by Named Geographic Region
HTTPS Endpoint
The following endpoint is used with HTTPS GET:
Request Parameter
The following query string parameters are used with the Budget API endpoint:
Parameter | Description | Required | Valid Values | Examples |
---|---|---|---|---|
publisher | The publisher code that identifies you. This parameter is required so that we can reflect the accurate budget. | Yes | Contact your account manager for your publisher code. | acme |
what | What a user is searching for. For multi-word searches, simply put a space between the words. | Yes | A URL-Encoded string value | pizza |
where | The geographic location, generally a zip code or city-state pair. | Yes | A zip code, city-state pair, or street address. Spaces are optional following the comma between a city and state. | 91011 |
rpp | The maximum number of results to return. The default value is 10. Values over 100 will be clamped to 10. | No | Integers in the range 1 through 100. | 3 |
format | The desired format for the results. Default value xml | No | json, xml | xml |
includeBudgetId | This parameter decides if the budget allocation Id will be displayed in the result. Default is false. | No | true, false | true |
Obtaining Budget Available by Latitude and Longitude
HTTPS Endpoint
The following endpoint is used with HTTPS GET:
Request Parameter
The following query string parameters are used with the Budget API endpoint:
Parameter | Description | Required | Valid Values | Examples |
---|---|---|---|---|
publisher | The publisher code that identifies you. This parameter is required so that we can reflect the accurate budget. | Yes | Contact your account manager for your publisher code. | acme |
lat | Latitude of the center of a circle for a geographic search. | Yes | A decimal between -90 and 90. | 37.65056 |
lon | Longitude of the center of a circle for a geographic search. | Yes | A decimal between -180 and 180. | -119.03639 |
radius | Radius of a circle search, in miles. Defaults to 5. If radius is larger than 25, it will be clamped to 25. | No | An integer between 1 and 25, inclusive. | 2 |
rpp | The maximum number of results to return. The default value is 10. Values over 100 will be clamped to 10. | No | Integers in the range 1 through 100. | 8 |
format | The desired format for the results. Default is xml. | No | json, xml | xml |
includeBudgetId | This parameter decides if the budget allocation Id will be displayed in the result. Default is false. | No | true, false | true |
Obtaining Budget Available by ID
HTTPS Endpoint
The following endpoint is used with HTTPS POST or GET:
Request Parameter
The following query string parameters are used with the Budget API endpoint:
Parameter | Description | Required | Valid Values | Examples |
---|---|---|---|---|
publisher | The publisher code that identifies you. This parameter is required so that we can reflect the accurate budget. | Yes | Contact your account manager for your publisher code. | acme |
ids | A comma separated string of CityGrid listing ids | Yes |
| 45654239,41783749,32636885 |
rpp | The maximum number of results to return. The default value is 10. Values over 100 will be clamped to 10. | No | Integers in the range 1 through 100. | 3 |
format | The desired format for the results. Default is xml. | No | json, xml | xml |
includeBudgetId | This parameter decides if the budget allocation Id will be displayed in the result. Default is false. | No | true, false | true |
Header Values for POST Requests
Header | Description | Required | Valid Values |
---|---|---|---|
Content-Type | Media type of the request body, if any | yes | application/json |
Usage Examples
The following table provides some examples uses of the Budget API and their corresponding URL with query parameters. Click on the links to try them out.
Usage | URL |
---|---|
Return listings with budget for restaurants in 90069 | http://api.citygridmedia.com/ads/budget/v2/where?publisher=test&what=restaurants&where=90069 |
Return listings with budget for restaurants within 5 miles of the specified lat/lon location | |
Return the budget information for the specified Places | http://api.citygridmedia.com/ads/budget/v2/detail?publisher=test&ids=45654239,41783749,32636885 |
Response
The Budget API results can be returned in both XML or JSON format.
The following table describes the return elements:
Element | Parent Element | Attributes | Description |
---|---|---|---|
ads |
|
|
|
ad | ads |
| Advertisement data |
listing_ids | ad |
| The group of businesses that shares the budget available |
listing_id | ad |
| The ID to uniquely identify CityGrid's businesses |
reference_id | ad | The ID to uniquely identify provider to which listing belongs to | |
ppe | ad |
| Price per event |
remaining_budget | ad |
| Budget available |
budget_allocation_id (optional) | ad | Budget allocation id available |
XML Output
The following is an example of an XML response:
<ads> <ad> <listing_ids> <listing_id>4740459</listing_id> <listing_id>174934</listing_id> </listing_ids> <reference_id>1</reference_id> <net_ppe>0.17728867898596223</net_ppe> <budget_remaining>97.49548319047202</budget_remaining> </ad> <ad> <listing_ids> <listing_id>609752</listing_id> </listing_ids> <reference_id>1</reference_id> <net_ppe>1.5468694912910876</net_ppe> <budget_remaining>96.36092528669207</budget_remaining> </ad> <ad> <listing_ids> <listing_id>4743772</listing_id> </listing_ids> <reference_id>1</reference_id> <net_ppe>0.9577210507033189</net_ppe> <budget_remaining>95.46137700585184</budget_remaining> </ad> </ads>
XML Output with parameter includeBudgetId
In the case of an XML, the file downloaded will look like the following:
<ads> <ad> <listing_ids> <listing_id>1000004</listing_id> </listing_ids> <reference_id>11</reference_id> <net_ppe>0.55</net_ppe> <budget_remaining>100000.0</budget_remaining> <budget_allocation_id>267382</budget_allocation_id> </ad> </ads>