Page Comparison

...

Info
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.

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.

...

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

Code Block
httphttps://api.citygridmedia.com/ads/custom/v2/where

...

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

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

...

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 where, the Specifying Where section in the Places API topic provides more details.

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	http://api.citygridmedia.com/ads/custom/v2/where?what=restaurant&where=los%20angeles,CA&publisher=test
Return restaurants for postal code 90069	http://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	http://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	http://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	http://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	http://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.”	http://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	http://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 HTTP Endpoint

The following endpoint supports HTTP GET:

Code Block
http://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_network	Property for storing the network for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric	Google, Bing, Ezanga etc.
sem_network_source	Property for storing network source for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		Search network, Run of network, google.com etc.
sem_affiliate_id	Property for storing an affiliate id for you to optimize your marketing campaigns against, if you do marketing	No	Integer		Publisher id e.g. 3
sem_sub_affiliate_id	Property for storing sub-affiliate_id for you to optimize your marketing campaigns against, if you do marketing	No	Integer		Sub-publisher id e.g. 21
sem_campaign_id	Property for storing campaign id for you to optimize your marketing campaigns against, if you do marketing	No	Integer		45723
sem_adgroup_id	Property for storing adgroup id you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		Generic Auto Parts
sem_creative_id	Property for storing creative id for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		swf1
sem_query	Property for storing a query for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		pizza, sporting goods
sem_matched_keyword	Property for storing a matched keyword for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		construction
sem_device	Property for storing the device for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		mobile device, desktop etc.

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

Anchor

	WhereNotes
	WhereNotes

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 where, the Specifying Where section in the Places API topic provides more details.

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:

Code Block
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_network	Property for storing the network for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		Google, Bing, etc.
sem_network_source	Property for storing network source for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		Search network, Run of network, google.com etc.
sem_affiliate_id	Property for storing an affiliate id for you to optimize your marketing campaigns against, if you do marketing	No	Integer		Publisher id e.g. 3
sem_sub_affiliate_id	Property for storing sub-affiliate_id for you to optimize your marketing campaigns against, if you do marketing	No	Integer		Sub-publisher id e.g. 21
sem_campaign_id	Property for storing campaign id for you to optimize your marketing campaigns against, if you do marketing	No	Integer		45723
sem_adgroup_id	Property for storing adgroup id you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		Generic Auto Parts
sem_creative_id	Property for storing creative id for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		swf-1
sem_query	Property for storing a query for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		pizza sporting goods
sem_matched_keyword	Property for storing a matched keyword for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		construction
sem_device	Property for storing the device for you to optimize your marketing campaigns against, if you do marketing	No	Alphanumeric		mobile device, desktop etc.

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

...

Usage	URL
Return restaurants for an area described by latitude, longitude and radius	httphttps://api.citygridmedia.com/ads/custom/v2/latlon?what=restaurant&lat=38.5654&lon=-121.46753&radius=5&publisher=test
Same as above, but limited to 10 responses	httphttps://api.citygridmedia.com/ads/custom/v2/latlon?what=restaurant&lat=38.5654&lon=-121.46753&radius=5&max=10&publisher=test

...

The mapping url must have the following form:

Code Block

	XML
	XML

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

...

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.

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

...

The following is an example of an XML response:

Code Block

	xml
	xml


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

...

Errors are indicated in the HTTP HTTPS response as follows:

HTTP 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

Versions Compared

Old Version 11

New Version Current

Key

Contents

Audience

Where

HTTPS Endpoint

Where Usage Examples

Obtaining Custom Ads by Latitude and Longitude

LatLon HTTP Endpoint

LatLon Request

Where Usage Examples

Obtaining Custom Ads by Latitude and Longitude

LatLon HTTPS Endpoint

LatLon Request