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

Custom Ads API

Introduction

As a CityGrid partner, you can place CityGrid ads on your web and mobile applications and get paid when your users click on them. Ads can be obtained by requests to the Custom Ads API, which provide you raw advertisement data in XML, leaving you free to customize all look-and-feel aspects of the display, including formatting, colors, and fonts.

Advertisements are requested by category and geography. Consider an application in which a user searches for "restaurants". The application has previously determined that the user is located in or near Santa Monica, CA, and has left that information in a cookie. The application can create relevant CityGrid advertisements by using "restaurants" and "Santa Monica, CA" as arguments when making a call to the Custom Ads API.

The Custom Ads API contains two endpoints: one for which the location is defined in terms of the name of a geographic region, and the other for which it is defined in terms of latitude and longitude.

Custom Ads by design contain no display information. If you wish to obtain pre-redendered ad units from CityGrid, see the Web Ads API for ads you can display on desktop browsers or the Mobile Ads API for ads you can display on mobile native and web applications.

Contents

Audience

The Custom Ads API is intended for developers of web and mobile applications who want place custom advertisements from CityGrid into their applications to earn credit when the advertisement is clicked. Custom advertisements are ads which do not contain display information; instead, publishers are free to match their application's look-and-feel when rendering ad data.

Version 2 Updates

  • Changes to results elements
    • Added impression id, i
  • The ad_destination_url is now an obfuscated URL. This URL will be decrypted and the proper redirect will take place when this link is followed.

Obtaining Custom Ads by Named Geographic Region

The where endpoint returns custom ads using a region (city, neighborhood, or metro) name or zip code. It is useful for free-form text and broad geographical region-based searches.

Where HTTPS Endpoint

The following endpoint is used with HTTPS GET:

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

Where Request

The following query string parameters are used with the Custom Ads API where endpoint:

Parameter

Description

Required

Valid Values

Default

Examples

Notes

what

What a user is searching for

Yes

 

 

pizza
sporting%20goods
plumbers

 

where

The geographic location, generally a zip code or city-state pair

See Notes below

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

 

raw_what

The original user search phrase if available.

No

 

 

italian%20food
plumbing%20work

 

raw_where

The original user search phrase if available.

No

 

 

los%20angeles

 

radius

Radius of a circle search using client_ip.

No

An integer between 1 and 25, inclusive

25

2

If radius is larger than 25, it defaults to 25

publisher

The publisher code that identifies you

Yes

 

 

acme

This parameter is required so that we know who to credit

max

The Number of ads that you want to be returned

Yes

Integers, 1 through 10

10

3

Values over 10 will only return 10 results

placement

An optional property for storing additional information you would like CityGrid Media to log for this view

No

 

 

google
yahoo
searchresults

An example: if you are re-syndicating advertisements, you can use this parameter to record the ultimate destination for the advertisement. If you are placing CityGrid advertisements on your own site, you can record where on your site the advertisement will be placed

mapping_url

A callback URL

No

 

 

See #Mapping URL for more information.

client_ip

The IP address of your client

See Notes below

IPv4 or IPv6

 

17.148.221.102

This is used to determine a geography if the where parameter is not supplied

user_agent

The version of browser or device the ad is served on

No

 

The user agent value from the request header

Mozilla%2F5.0+%28BlackBerry%3B+U%3B+BlackBerry+9800%3B
+en-US%29+AppleWebKit%2F534.1%2B+%28KHTML%2C+like
+Gecko%29+Version%2F6.0.0.246+Mobile+Safari%2F534.1%2B

 

serve_url

The URL of the requested page

No

 

 

http%3A%2F%2Fnational.citysearch.com%2Fprofile%2F10843791
%2Fbremerton_wa%2Fgehring_brothers_guns.html

 

sem_networkProperty for storing the network for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Google, Bing, Ezanga etc. 
sem_network_sourceProperty for storing network source for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Search network, Run of network, google.com etc. 
sem_affiliate_idProperty for storing an affiliate id for you to optimize your marketing campaigns against, if you do marketingNoInteger Publisher id e.g. 3 
sem_sub_affiliate_idProperty for storing sub-affiliate_id for you to optimize your marketing campaigns against, if you do marketingNoInteger Sub-publisher id e.g. 21 
sem_campaign_idProperty for storing campaign id for you to optimize your marketing campaigns against, if you do marketingNoInteger 45723 
sem_adgroup_idProperty for storing adgroup id you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Generic Auto Parts 
sem_creative_idProperty for storing creative id for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric swf1 
sem_queryProperty for storing a query for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric pizza, sporting goods 
sem_matched_keywordProperty for storing a matched keyword for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric construction 
sem_device Property for storing the device for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric mobile device, desktop etc. 

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).


Notes

  • To define a geography, you must either specify where or client_ip. If you specify both, then where will be used, and client_ip will be ignored.
  • For client_ip, you may specify a radius to indicate a circle around the location of the IP address. If no radius is specified, then a radius of 25 miles is used.

Where Usage Examples

The following table provides some example uses of the Custom Ads API and their corresponding URL with query parameters. Click on the links to try them out.

Usage

URL

Return restaurants in Los Angeles

https://api.citygridmedia.com/ads/custom/v2/where?what=restaurant&where=los%20angeles,CA&publisher=test

Return restaurants for postal code 90069

https://api.citygridmedia.com/ads/custom/v2/where?what=restaurant&where=90069&publisher=test

Return restaurants for a user at IP address 4.74.197.0

https://api.citygridmedia.com/ads/custom/v2/where?what=restaurant&client_ip=4.74.197.0&publisher=test

Return up to 5 spas near zip code 90069

https://api.citygridmedia.com/ads/custom/v2/where?where=90069&what=spa&publisher=test&max=5

Return up to 10 bars in Detroit. Note that 10 is the default maximum

https://api.citygridmedia.com/ads/custom/v2/where?where=Detroit,MI&what=bar&publisher=test

Return up to 10 bakeries for whatever region the user with IP 23.110.26.29 resides

https://api.citygridmedia.com/ads/custom/v2/where?what=bakery&client_ip=23.110.26.29&publisher=test

Return up to 10 pet businesses in Reno, telling CityGrid you would like this request logged under the placement identifier “magazine.”

https://api.citygridmedia.com/ads/custom/v2/where?where=reno,nv&what=pet&placement=magazine&publisher=test

Return up to 10 bars near zip code 90004, including an XML schema location with the results

https://api.citygridmedia.com/ads/custom/v2/where?where=90004&what=bar&publisher=test&schema=true

Obtaining Custom Ads by Latitude and Longitude

The latlon endpoint returns custom ads using a geographic region defined by latitude and longitude.

LatLon HTTPS Endpoint

The following endpoint supports HTTPS GET:

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

LatLon Request

The following query string parameters are used with the Custom Ads API latlon endpoint:

Parameter

Description

Required

Valid Values

Default

Examples

Notes

what

What a user is searching for

Yes

 

 

pizza 
sporting%20goods 
plumbers

 

lat

Latitude of the center of a circle for a geographic search

See Notes below

 

 

37.65056

 

lon

Longitude of the center of a circle for a geographic search.

See Notes below

 

 

-119.03639

 

radius

Radius of a circle search.

See Notes below

An integer between 1 and 50, inclusive

4

2

If radius is larger than 25, it defaults to 25

raw_what

The original user search phrase if available.

No

 

 

italian%20food
plumbing%20work

 

raw_where

The original user search phrase if available.

No

 

 

los%20angeles

 

publisher

The publisher code that identifies you

Yes

 

 

acme

This parameter is required so that we know who to credit

max

The Number of ads that you want to be returned

Yes

Integers, 1 through 10

10

3

Values over 10 will only return 10 results

placement

An optional property for storing additional information you would like CityGrid Media to log for this view

No

 

 

google
yahoo
searchresults

An example: if you are re-syndicating advertisements, you can use this parameter to record the ultimate destination for the advertisement. If you are placing CityGrid advertisements on your own site, you can record where on your site the advertisement will be placed

mapping_url

A callback URL

No

 

 

See #Mapping URL for more information.

client_ip

The IP address of your client

See Notes below

IPv4 or IPv6

 

17.148.221.102

This is used to determine a geography if the where parameter is not supplied

user_agent

The version of browser or device the ad is served on

No

 

The user agent value from the request header

Mozilla%2F5.0+%28BlackBerry%3B+U%3B+BlackBerry+9800%3B
+en-US%29+AppleWebKit%2F534.1%2B+%28KHTML%2C+like
+Gecko%29+Version%2F6.0.0.246+Mobile+Safari%2F534.1%2B

 

serve_url

The URL of the requested page

No

 

 

http%3A%2F%2Fnational.citysearch.com%2Fprofile%2F10843791
%2Fbremerton_wa%2Fgehring_brothers_guns.html

 

sem_networkProperty for storing the network for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Google, Bing, etc. 
sem_network_sourceProperty for storing network source for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Search network, Run of network, google.com etc. 
sem_affiliate_idProperty for storing an affiliate id for you to optimize your marketing campaigns against, if you do marketingNoInteger Publisher id e.g. 3 
sem_sub_affiliate_idProperty for storing sub-affiliate_id for you to optimize your marketing campaigns against, if you do marketingNoInteger Sub-publisher id e.g. 21 
sem_campaign_idProperty for storing campaign id for you to optimize your marketing campaigns against, if you do marketingNoInteger 45723 
sem_adgroup_idProperty for storing adgroup id you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Generic Auto Parts 
sem_creative_idProperty for storing creative id for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric swf-1 
sem_queryProperty for storing a query for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric pizza
sporting goods
 
sem_matched_keywordProperty for storing a matched keyword for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric construction 
sem_device Property for storing the device for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric mobile device, desktop etc. 

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).


Notes

  • To define a geography, you must either specify lat, lon, and radius, or else client_ip. If you specify both, then lat/lon/radius will be used, and client_ip will be ignored.
  • For client_ip, you may specify a radius to indicate a circle around the location of the IP address. If no radius is specified, then a radius of 25 miles is used.

LatLon Usage Examples

The following table provides some example uses of the Custom Ads API and their corresponding URL with query parameters. Click on the links to try them out.

Mapping URL

The mapping url is an optional ad callback URL.

The mapping_url parameter is not commonly used. Work with your account manager if you are interested in using a callback.

The mapping url must have the following form:

    https://<hostname>/<path>?impressionId=${adImpressionId}&referenceId=${refId}&listingId=${listingId}&cgRefId=${cgRefId}&actionTarget=${actionTarget}

Here <hostname> and <path> are provided by you; the API will generate the tracking information and replace the ${...} placeholders to provide the actual callback URL. You must provide parameter names and placeholders, exactly as specified above, for impressionId, referenceId, listingId, and cgRefId. Only actionTarget is optional.

The URL should be encoded before passing it as a parameter in the request.

Response

The Custom Ads Where results are returned in XML.

The following table describes the return elements:

Element

Parent Element

Description

ads

 

Top level container of advertisement elements

ad

ads

Advertisement data

id

ad

The ID to uniquely identify the ad

impression_id

ad

The impression ID returned per ad

type

ad

The type of the ad. Always "local PFP", which indicates the ad to be local Pay For Performance

listing_id

ad

The ID to uniquely identify CityGrid's businesses

name

ad

The name of the advertiser's business

street

ad

The street address of the business

city

ad

The city of the business

state

ad

The state of the business

zip

ad

The postal code of the business

latitude

ad

The latitude of the business

longitude

ad

The longitude of the business

phone

ad

The phone number of the business

tagline

ad

The tagline of the business (always one line)

description

ad

A description of the business

overall_review_rating

ad

The rating of the business

ad_destination_url

ad

The obfuscated url target of a click on the ad. This url is not visibly aesthetic, because it contains a number of tracking parameters

ad_display_url

ad

A clean, but fake, url to show on a page, so end users are comfortable clicking on the associated ad

ad_image_url

ad

The url of the image to display with the ad

gross_ppe

ad

Price per event

offers

ad

Offers the business is currently offering

reviews

ad

Reviews of the business

distance

ad

Distance the business is located from latitude/longitude provided. (Only provided for lat/lon Search)

attribution_text

ad

The attribution text from our ads partners. This text must be displayed if attribution_text is provided.

character data is required to be escaped, so you will likely see the character entities for ", &, >, <, and '.

XML Output

The following is an example of an XML response:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<ads>
  <!-- Copyright 2011 CityGrid -->
  <ad id="46765212">
    <impression_id>f777cba07607441e9ad8c67896bb61b0</impression_id>
    <type>local PFP</type>
    <listing_id>160089</listing_id>
    <name>Nawab of India</name>
    <street>1621 Wilshire Blvd</street>
    <city>Santa Monica</city>
    <state>CA</state>
    <zip>90403</zip>
    <latitude>34.0286</latitude>
    <longitude>-118.4869</longitude>
    <phone>3105847733</phone>
    <tagline>Exotic Indian Cuisine</tagline>
    <description/>
    <overall_review_rating>7</overall_review_rating>
    <ad_destination_url>http://pfpc.citygridmedia.com/pfp/ad/v2?
X7MFxm8prCBE3CqXUCtlE0UUuNO5pBYbX06LlRR3AAYnzLu4JPHmAVWlQsIhzkUkcuGU9iP0fi3n1cTOm2rDZYC8g5kvEzOeKTbqq0kOLs8KyIcaIENB0fL7wWxAg-aUimQMlKfw18-
019ihs_CtFKHqwORNXqZDUmDSlb03r7mAezr7aL7qOiZkr8HB_o7tYXkA37emJ7ldX0r51uG9xAfgbHqe61n-3szsh4fhb-W3tjiZT1dN8iH4_WeuS2XIYpDf9MDWUESLkcH2zO3r5TqOj6ht316M3OIIPUq55kVb9QytsGaYWA</ad_destination_url>
    <ad_display_url>http://www.citysearch.com/profile/160089</ad_display_url>
    <ad_image_url>http://images.citysearch.net/assets/imgdb/advertorial_profile/d3/e8/V-LOSCA-55109833_ID216108_guide_inclusion.jpg</ad_image_url>
    <gross_ppe>0.13</gross_ppe>
    <reviews>25</reviews>
    <offers/>
    <distance/>
    <attribution_text/>
  </ad>
</ads>

Error Codes

Errors are indicated in the HTTPS response as follows:

HTTPS Status Code

Type

Message

Description

403

Status report

Invalid 'publisher' parameter

Access to the specified resource has been forbidden because of an invalid publisher parameter.

403

Status report

Missing 'publisher' parameter

Access to the specified resource has been forbidden because of a missing publisher parameter.

403

Status report

Missing 'what' parameter

Access to the specified resource has been forbidden because of a missing what parameter.

403

Status report

Missing 'where' or 'lat' and 'lon' or 'client_ip' parameter

Access to the specified resource has been forbidden because of missing location information (where, lat and lon, or client_ip).

403

Status report

Invalid 'max' parameter

Access to the specified resource has been forbidden because of an invalid max parameter

403

Status report

Invalid 'lat' parameter

Access to the specified resource has been forbidden because of an invalid lat parameter

403

Status report

Invalid 'lon' parameter

Access to the specified resource has been forbidden because of an invalid lon parameter