Page Comparison

...

Parameter	Description	Required	Valid Values	Examples
publisher	The publisher code that identifies you. This parameter is required so that we know who to credit.	Yes	Contact your account manager for your publisher code.	acme
collection_id	Used for rotation or targeting. A publisher can have multiple collections and is required to pass one collection id per request.	Yes	A predefined id that holds template information. See Collection IDs for more information.	web-001-630x100 web-003-468x60
width	The width of the ad slot.	Yes	An integer in pixels.	300
height	The height of the ad slot.	Yes	An integer in pixels.	250
what	What a user is searching for. For multi-word searches, simply put a space between the words.	Yes		pizza sporting%20goods sporting goods plumbers
where	The geographic location, generally a zip code or city-state pair.	Yes, if lat and lon are not provided.	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
lat	Latitude of the center of a circle for a geographic search.	Yes, if where is not specified	A decimal between -90 and 90.	37.65056
lon	Longitude of the center of a circle for a geographic search.	Yes, if where is not specified	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.	Yes, if lat and lon are specified	An integer between 1 and 25, inclusive.	2
raw_what	The original user search phrase if available.	No		italian%20food italian food plumbing%20work plumbing work
raw_where	The original user search phrase if available.	No		los%20angeles
max	The maximum number of results to return. The default value is 10. Values over 10 will be clamped to 10.	No	Integers in the range 1 through 10.	3
i	The impressionId that you obtained from a previous CityGrid API call.	No		0007000008b8b6fd23eb3c463ab3fdcc5b04f6ad13
placement	An optional property for storing additional information you would like CityGrid Media to log for this view. For 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.	No		google yahoo searchresults
client_ip	The IP address of your client.	No	IPv4 or IPv6	17.148.221.102
user_agent	The version of browser or device the ad is served on.	No		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
mapping_url	Click-throughs are mapped to the specified URL.	No	See #Mapping URL for more information. No		http%3A%2F%2Fwww.citygrid.com%2Fparse%3FimpressionId%3D %24%7BadImpressionId%7D%26referenceId%3D%24%7BrefId %7D%26listingId%3D%24%7BlistingId%7D%26cgRefId%3D %24%7BcgRefId%7D%26actionTarget%3D%2%7BactionTarget%7D

...

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

Notes

If all three of where, lat, and lon are provided, the lat and lon values take precedence.

...

The mapping url is an optional ad callback URLad click-through url. When utilized, the API will replace the click-through urls with the mapping_url for all local ad listing results. Click-through urls for backfill ad results will not be modified.

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

The mapping url must have the following form:

Code Block

	XML
	XML


  
 http://<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 substitute 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.

...

click-through url.

You may pass mapping_url just as any other javascript parameters in the ad call.

Code Block

	XML
	XML


<script type="text/javascript">
  new CityGrid.Ads('sidebar_ad_slot', {
    collection_id: 'web-001-630x100',
    publisher: 'citysearch',
    what: 'sushi',
    where: '90069',
    lat: 34.088188,
    lon: -118.37205,
    width: 630,
    height: 100,
    mapping_url: "http://www.citygrid.com/adredirect?impressionId=${adImpressionId}&referenceId=${refId}&listingId=${listingId}&cgRefId=${cgRefId}"
  });
</script>

The click-through of any local ad listing results will then redirect users to the following url. Publishers can use this information to send users to pages of their choice.

Code Block
http://www.citygrid.com/adredirect?impressionId=00070000063e8cd424d9dd42eba9589c458a58b339&referenceId=1&listingId=47405288&cgRefId=bc1a153dc3354075bb73d948e2f51914

Errors

Errors are indicated in the HTTP response as follows:

...

The following are examples of default house ads for collection id web-002-300x250:

Note
CityGrid may also use publisher-provided custom house advertisement images. Work with your account manager if you are interested in using this feature.

Versions Compared

Old Version 6

New Version 7

Key

Errors