com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'html' is unknown.

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

includeBudgetIdThis parameter decides if a budget allocation Id would show in the result. Default is false.Notrue, falsetrue

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

citieslisting List of cities associated to this advertiser
citycities City associated to this advertiser
postal_codeslisting List of postal codes associated to this advertiser
postal_codepostal_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:

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

includeBudgetIdThis parameter decides if the budget allocation Id will be displayed in the result. Default is false.Notrue, falsetrue

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

includeBudgetIdThis parameter decides if the budget allocation Id will be displayed in the result. Default is false.Notrue, falsetrue

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

includeBudgetIdThis parameter decides if the budget allocation Id will be displayed in the result. Default is false.Notrue, falsetrue

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

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