Page Comparison

...

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 HTTPS HTTP GET:

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

...

adad

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		List of markets Market associated to this advertiser
neighborhoods	listing		List of neighborhoods associated to this advertiser
neighborhood	neighborhood		Neighborhood associated to this advertiserppe
cities	listing		Price per event	remaining_budget	List of cities associated to this advertiser
city	cities		Budget available
budget_allocation_id (optional)	ad		Budget allocation id available

Header Values

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

...

Code Block

borderStyle	dashed
lang	xml

<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>
    </listing>      <city>Los <listing>Angeles</city>
        <listing_id>3333</listing_id>
		<listing_name>abc Inc</listing_name>
		<reference_id>1</reference_id>  <city>San Diego</city>
        </cities>
<categories>        <postal_codes>
  <category primary="true">Attorneys</category>       <postal_code>99999</postal_code>
   <category>Wrongful Death Attorneys</category>     <postal_code>11111</postal_code>
   </categories>     </postal_codes>
   <markets>   </listing>
      <listing>
<market>West Palm Beach-Boca Raton-Boynton Beach, FL</market>   <listing_id>3333</listing_id>
		<listing_name>abc   Inc</listing_name>
		<reference_id>1</reference_id>
   <market>Ocala, FL</market>    <categories>
    </markets>      <category primary="true">Attorneys</category>
 <neighborhoods>         <category>Wrongful Death <neighborhood>WaterAttorneys</category>
Catchment Area</neighborhood>       </categories>
   <neighborhood>Golden Lakes</neighborhood>    <markets>
    </neighborhoods>      <market>West </listing>
    </listings>Palm Beach-Boca Raton-Boynton Beach, FL</market>
   </ad>   <ad>    <market>Ocala, <ppe>2.0</ppe>FL</market>
      <remaining_budget>32.0</remaining_budget>  </markets>
  <listings>      <neighborhoods>
<listing>         <listing_id>2222</listing_id>
		<listing_name>stores Inc</listing_name>
		<reference_id>1</reference_id> <neighborhood>Water Catchment Area</neighborhood>
        <categories>  <neighborhood>Golden Lakes</neighborhood>
       <category>Overnight Shipping<</category>
neighborhoods>
		<cities/>	
        <postal_codes/>
<category>Commercial Shipping</category>
        </categories>listing>
    </listings>
   <markets></ad>
  <ad>
    <ppe>2.0</ppe>
  <market>Cape Coral-Fort Myers, FL</market> <remaining_budget>32.0</remaining_budget>
     <listings>
    <market>Naples-Marco Island, FL</market><listing>
        </markets>
 <listing_id>2222</listing_id>
		<listing_name>stores Inc</listing_name>
		<reference_id>1</reference_id>
        <neighborhoods><categories>
          <neighborhood>North<category>Overnight Naples<Shipping</neighborhood>category>
          <neighborhood>Urban<category>Commercial Estates<Shipping</neighborhood>category>
        </neighborhoods>categories>
      </listing>  <markets>
    <listing>      <market>Cape Coral-Fort Myers, <listing_id>4444</listing_id>
		<listing_name>ZZZ Inc</listing_name>
		<reference_id>1</reference_id>FL</market>
          <market>Naples-Marco Island, FL</market>
<categories>        </markets>
  <category primary="true">Attorneys</category>     <neighborhoods>
     <category>Wrongful Death Attorneys</category>   <neighborhood>North Naples</neighborhood>
    </categories>      <neighborhood>Urban Estates</neighborhood>
 <markets>       </neighborhoods>
		<cities/>
  <market>West Palm Beach-Boca Raton-Boynton Beach, FL</market>  <postal_codes/>
      </listing>
      <listing>
<market>Ocala, FL</market>       <listing_id>4444</listing_id>
		<listing_name>ZZZ <Inc</markets>
listing_name>
		<reference_id>1</reference_id>
       <neighborhoods> <categories>
         <neighborhood>Water Catchment Area</neighborhood><category primary="true">Attorneys</category>
          <neighborhood>Golden<category>Wrongful Death Lakes<Attorneys</neighborhood>category>
        </neighborhoods>categories>
        <markets>
          <market>West Palm Beach-Boca Raton-Boynton Beach, </listing>FL</market>
          <market>Ocala, </listings>FL</market>
        </ad>
</ads>

XML Output with parameter includeBudgetId

In the case of an XML, the file downloaded will look like the following:

Code Block

xml

<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>
	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:

Code Block

	xml
	xml

<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 HTTPS connection 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.

...

To connect to the Discovery API, form an HTTPS 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.

...

Code Block

lang	html

Client: (Using HttpClient, Framework independent)

String endpoint = " httpshttp://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();
}

...

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:

...

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:

...

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:

...

Usage	URL
Return listings with budget for restaurants in 90069	httpshttp://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	httpshttp://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	httpshttp://api.citygridmedia.com/ads/budget/v2/detail?publisher=test&ids=45654239,41783749,32636885

...

Versions Compared

Old Version 11

New Version Current

Key

HTTP Endpoint

Header Values

Header Values

XML Output with parameter includeBudgetId

XML Output with parameter includeBudgetId

Connecting to the streaming Discovery API

Obtaining Budget Available by Named Geographic Region

HTTPS Endpoint

Request Parameter

Obtaining Budget Available by Latitude and Longitude

HTTPS Endpoint

Request Parameter

Obtaining Budget Available by ID

HTTPS Endpoint

Request Parameter