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

Budget API V4 (For call publishers)

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.

 

New v4 endpoints

As of September 2016 a new version of the Budget API, called v4, has been introduced. There are three major changes compared to the previous v2 version:

  • It now has information about call settings from call advertisers like call duration minimum, dedupe period, and phone number of the advertiser.
  • It introduces the concept of Day Parting meaning advertisers can now choose at what time of the day they want their ads to be distributed. You can use the v4 endpoints to determine whether the budget is available at a given time of the day.
  • Previously, budget was always given for all the listings in the ad, in v4 the budget is still present at the ad level but in addition there is a new field called "remaining_budget_override" that provides a specific budget for the listing (if different from the ad budget)

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

http://stream.api.citygridmedia.com/ads/budget/v4/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

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.

Xsd schema available at:

http://stream.api.citygridmedia.com/ads/budget/v4/discover/schema?publisher=<publisher_code>

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

ppead Price per event
budget_allocation_idad Budget allocation id
call_duration_seconds_minimumad (Nullable) Minimum call duration for a phone call to be eligible for billing
dedupe_periodad (Nullable) period for which calls from a same caller number on the same advertiser will be deduped
dedupe_unitad (Nullable) unit of the dedupe period, for eg. days, hours, months etc.
remaining_budgetad Budget available
day_parting_settingsad (Nullable) Day parting settings for this ad and day (apply to all listings in the ad) if any specified by the advertiser
windowsday_parting_settings List of day parting windows
windowwindows 

A window of time within which the budget is available

start_timewindow The start time of the day parting window (formatted using xml native "time" format)
end_timewindow The end time of the day parting window (formatted using xml native "time" format)
listingsad The group of businesses sharing the same budget
listinglistings Data of a business location

listing_id

listing

 

The ID to uniquely identify CityGrid's businesses

listing_namelisting The name of the business
reference_idlisting The ID to uniquely identify provider to which listing belongs to
in_day_partinglisting Boolean that indicates weather or not the advertiser accepts connections at the current time of the day
remaining_budget_overridelisting (Nullable) Budget available for this listing if different from remaining_budget
phone_numberlisting (Nullable) phone number for the advertiser listing

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

neighborhoods

 

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
day_parting_settings_overrideslisting (Nullable) Day parting settings that apply for this particular listing if different from day_parting_settings

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>
	<budget_allocation_id>111</budget_allocation_id>
    <call_duration_seconds_minimum>30</call_duration_seconds_minimum>
    <dedupe_period>1</dedupe_period>
    <dedupe_unit>days</dedupe_unit>
    <listings>
      <listing>
        <listing_id>1111</listing_id>
    	<listing_name>XYZ Inc</listing_name>
    	<reference_id>1</reference_id>
    	<in_day_parting>true</in_day_parting>
		<phone_number>8008001111</phone_number>
     	<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>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008003333</phone_number>
        <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>
    <budget_allocation_id>222</budget_allocation_id>
    <call_duration_seconds_minimum>8</call_duration_seconds_minimum>
    <listings>
      <listing>
        <listing_id>2222</listing_id>
        <listing_name>stores Inc</listing_name>
        <reference_id>1</reference_id>
        <in_day_parting>false</in_day_parting>
		<phone_number>8008002222</phone_number>
        <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>
        <in_day_parting>true</in_day_parting>
        <phone_number>8008004444</phone_number>
        <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 when remaining budget override is present

<ads>
  <ad>
    <ppe>0.2</ppe>
    <remaining_budget>3.0311</remaining_budget>
    <budget_allocation_id>16369425</budget_allocation_id>
    <call_duration_seconds_minimum>8</call_duration_seconds_minimum>
    <listings>
      <listing> 
        <listing_id>838628150</listing_id>
        <listing_name>Mojo's Seafood &amp; Chicken</listing_name>
        <reference_id>7</reference_id>
        <in_day_parting>true</in_day_parting>
        <remaining_budget_override>1.005</remaining_budget_override>
		<phone_number>8008008150</phone_number>
        <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>

XML Output when day parting settings are present

<ads>
  <ad>
    <ppe>0.2</ppe>
    <remaining_budget>3.0311</remaining_budget>
	<budget_allocation_id>16369425</budget_allocation_id>
	<call_duration_seconds_minimum>8</call_duration_seconds_minimum>
    <day_parting_settings>
      <windows>
        <window>
          <start_time>09:00:00.000-07:00</start_time>
          <end_time>18:00:00.000-07:00</end_time>
        </window>
      </windows>
    </day_parting_settings>
    <listings>
      <listing> 
        <listing_id>838628150</listing_id>
        <listing_name>Mojo's Seafood &amp; Chicken</listing_name>
        <reference_id>7</reference_id>
        <in_day_parting>true</in_day_parting>
        <remaining_budget_override>1.005</remaining_budget_override>
		<phone_number>8008008150</phone_number>
        <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>

XML Output when day parting settings override are pressent

<ads>
  <ad>
    <ppe>0.2</ppe>
    <remaining_budget>3.0311</remaining_budget>
	<budget_allocation_id>16369425</budget_allocation_id>
	<call_duration_seconds_minimum>8</call_duration_seconds_minimum>
    <day_parting_settings>
      <windows>
        <window>
          <start_time>09:00:00.000-07:00</start_time>
          <end_time>18:00:00.000-07:00</end_time>
        </window>
      </windows>
    </day_parting_settings>
    <listings>
      <listing> 
        <listing_id>838628150</listing_id>
        <listing_name>Mojo's Seafood &amp; Chicken</listing_name>
        <reference_id>7</reference_id>
        <in_day_parting>false</in_day_parting>
		<phone_number>8008008150</phone_number>
        <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>
        <day_parting_settings_override>
          <windows>
            <window>
             <start_time>08:00:00.000-07:00</start_time>
             <end_time>14:00:00.000-07:00</end_time>
           </window>
         </windows>
       </day_parting_settings_override>
      </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 (using Apache HttpClient):

String endpoint = " http://stream.api.citygridmedia.com/ads/budget/v4/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/v4/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

includeOutsideDayParting

This parameter decides if listings that are at the moment not available because of day parting are included in the response. Default is falseNotrue, falsefalse

 

Obtaining Budget Available by Latitude and Longitude

HTTPS Endpoint

The following endpoint is used with HTTPS GET:

https://api.citygridmedia.com/ads/budget/v4/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

includeOutsideDayPartingThis parameter decides if listings that are at the moment not available because of day parting are included in the response. Default is falseNotrue, falsefalse

Obtaining Budget Available by ID

HTTPS Endpoint

The following endpoint is used with HTTPS POST or GET:

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

Request Parameter

The following query string parameters are used with the Budget API endpoint:

Parameter

Description

Required

Valid Values

Examples

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

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

format

The desired format for the results. Default is xml.

No

json, xml

xml

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

Usage

URL

Return listings with budget for restaurants in 90069

https://api.citygridmedia.com/ads/budget/v4/where?publisher=test&what=restaurants&where=90069

Return listings with budget for restaurants within 5 miles of the specified lat/lon location

https://api.citygridmedia.com/ads/budget/v4/latlon?publisher=test&what=restaurants&lat=34.03&lon= -118.28&radius=5

Return the budget information for the specified Places

https://api.citygridmedia.com/ads/budget/v4/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

 

 

Root element

ad

ads

 

Advertisement data

net_ppe

ad

 

Price per event

reference_idad The ID to uniquely identify provider to which listing belongs to
budget_remainingad Budget available
budget_allocation_idad Budget allocation id available
call_duration_seconds_minimumad (Nullable) Minimum call duration for a phone call to be eligible for billing
dedupe_periodad (Nullable) period for which calls from a same caller number on the same advertiser will be deduped
dedupe_unitad (Nullable) unit of the dedupe period, for eg. days, hours, months etc.
day_parting_settingsad (Nullable) Day parting settings for this ad and day (apply to all listings in the ad) if any specified by the advertiser
windowsday_parting_settings List of day parting windows
windowwindows 

A window of time within which the budget is available

start_timewindow The start time of the day parting window (formatted using xml native "time" format)
end_timewindow The end time of the day parting window (formatted using xml native "time" format)
listingsad The group of businesses that shares the budget available
listinglistings Data for a given location

listing_id

listing

 

The ID to uniquely identify CityGrid's businesses

in_day_partinglisting Boolean that indicates weather or not the advertiser accepts connections at the current time of the day
remaining_budget_overridelisting (Nullable) Budget available for this listing if different from remaining_budget
phone_numberlisting (Nullable) phone number for the advertiser listing
day_parting_settings_overrideslistinglisting (Nullable) Day parting settings that apply for this particular listing if different from day_parting_settings

XML Output

The following is an example of an XML response:

<ads>
  <ad>
    <reference_id>1</reference_id>
    <net_ppe>0.17728867898596223</net_ppe>
    <budget_remaining>97.49548319047202</budget_remaining>
	<budget_allocation_id>11111</budget_allocation_id>
	<call_duration_seconds_minimum>30</call_duration_seconds_minimum>
	<dedupe_period>1</dedupe_period>
	<dedupe_unit>days</dedupe_unit>
    <listings> 
      <listing>
        <listing_id>4740459</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008000459</phone_number>
      </listing>
      <listing>
        <listing_id>174934</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008004934</phone_number>
      </listing>
    </listings>
  </ad>
  <ad>
    <reference_id>1</reference_id>
    <net_ppe>1.5468694912910876</net_ppe>
    <budget_remaining>96.36092528669207</budget_remaining>
	<budget_allocation_id>22222</budget_allocation_id>
	<call_duration_seconds_minimum>8</call_duration_seconds_minimum>
    <listings> 
      <listing>
        <listing_id>609752</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008009752</phone_number>
      </listing>
    </listings>
  </ad>
  <ad>
    <reference_id>1</reference_id>
    <net_ppe>0.9577210507033189</net_ppe>
    <budget_remaining>95.46137700585184</budget_remaining>
	<budget_allocation_id>33333</budget_allocation_id>
	<call_duration_seconds_minimum>8</call_duration_seconds_minimum>
    <listings> 
      <listing>
        <listing_id>4743772</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008003772</phone_number>
      </listing>
    </listings>
  </ad>
</ads>

XML Output with budget override

<ads>
  <ad>
    <reference_id>1</reference_id>
    <net_ppe>0.17728867898596223</net_ppe>
    <budget_remaining>97.49548319047202</budget_remaining>
	<budget_allocation_id>11111</budget_allocation_id>
	<call_duration_seconds_minimum>30</call_duration_seconds_minimum>
	<dedupe_period>1</dedupe_period>
	<dedupe_unit>days</dedupe_unit>
    <listings> 
      <listing>
        <listing_id>4740459</listing_id>
        <in_day_parting>true</in_day_parting>
        <budget_remaining_override>17.49548319047202</budget_remaining_override>
		<phone_number>8008000459</phone_number>
      </listing>
      <listing>
        <listing_id>174934</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008004934</phone_number>
      </listing>
    </listings>
  </ad>
</ads>

XML Output with day parting settings

<ads>
  <ad>
    <reference_id>1</reference_id>
    <net_ppe>0.17728867898596223</net_ppe>
    <budget_remaining>97.49548319047202</budget_remaining>
	<budget_allocation_id>11111</budget_allocation_id>
	<call_duration_seconds_minimum>30</call_duration_seconds_minimum>
	<dedupe_period>1</dedupe_period>
	<dedupe_unit>days</dedupe_unit>
    <day_parting_settings>
      <windows>
        <window>
          <start_time>09:00:00.000-07:00</start_time>
          <end_time>18:00:00.000-07:00</end_time>
        </window>
      </windows>
    </day_parting_settings>
    <listings> 
      <listing>
        <listing_id>4740459</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008000459</phone_number>
      </listing>
      <listing>
        <listing_id>174934</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008004934</phone_number>
      </listing>
    </listings>
  </ad>
</ads>

XML Output with day parting settings override

<ads>
  <ad>
    <reference_id>1</reference_id>
    <net_ppe>0.17728867898596223</net_ppe>
    <budget_remaining>97.49548319047202</budget_remaining>
	<budget_allocation_id>11111</budget_allocation_id>
	<call_duration_seconds_minimum>30</call_duration_seconds_minimum>
	<dedupe_period>1</dedupe_period>
	<dedupe_unit>days</dedupe_unit>
    <day_parting_settings>
      <windows>
        <window>
          <start_time>09:00:00.000-07:00</start_time>
          <end_time>18:00:00.000-07:00</end_time>
        </window>
      </windows>
    </day_parting_settings>
    <listings> 
      <listing>
        <listing_id>4740459</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008000459</phone_number>
      </listing>
      <listing>
        <listing_id>174934</listing_id>
        <in_day_parting>true</in_day_parting>
		<phone_number>8008004934</phone_number>
        <day_parting_settings_override>
          <windows>
            <window>
             <start_time>06:00:00.000-07:00</start_time>
             <end_time>14:00:00.000-07:00</end_time>
           </window>
         </windows>
        </day_parting_settings_override>
      </listing>
    </listings>
  </ad>
</ads>