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:

http://stream.api.citygridmedia.com/ads/budget/v2/discover

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 &amp; 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:

https://api.citygridmedia.com/ads/budget/v2/where

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 sporting%20goods
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 Pasadena,%20CA Cambridge,MA 1%20Main,Miami,FL
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:

https://api.citygridmedia.com/ads/budget/v2/latlon

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:

https://api.citygridmedia.com/ads/budget/v2/detail

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 application/xml

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	http://api.citygridmedia.com/ads/budget/v2/latlon?publisher=test&what=restaurants&lat=34.03&lon= -118.28&radius=5
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	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>