Introduction

The CityGrid Places API is available to any developer to create mobile applications or websites that display CityGrid place pages. As a CityGrid partner, however, you can publish CityGrid place pages and get paid when your users engage with the content of certain places. The program that monetizes the display of, and iteraction with, CityGrid places is called Places that Pay.

To use Places that Pay, make arrangements with our Partner Account Management team. Then simply use the Places API and a small amount of tracking code (described below) to display place pages. Everything else is handled by CityGrid.

Contents

Audience

Places that Pay is is intended for developers of Web and mobile applications who want to share advertising revenue for impressions and referrals.

Tracking

To share advertising revenue, simply notify CityGrid of impressions and referrals. Notification of impressions is done through JavaScript code (or, when JavaScript is not available, a tracking pixel) placed on a page, while notification of referrals is done by appending parameters to a URL.

Impression Tracking

In order for CityGrid to know that an element (such as a business profile, map, or review page) was displayed on your site, include the following JavaScript fragment on each page where you display our content, replacing the starred content with the relevant page-specific information described in the table that follows.

<script type="text/javascript">
    var _csv = {};
    _csv['action_target'] = '***';
    _csv['listing_id'] = '***';
    _csv['publisher'] = '***';
    _csv['reference_id'] = '***';
    _csv['placement'] = '***';
    _csv['mobile_type'] = '***';
    _csv['muid'] = '***';
    _csv['ua'] = '***';
    _csv['i']='***';
</script>
<script type="text/javascript" src="https://api.citygridmedia.com/ads/tracker/assets/api/scripts/tracker.js"></script>
<noscript>
    <img src='https://api.citygridmedia.com/ads/tracker/imp?action_target=***&listing_id=***&publisher=***&reference_id=***&placement=***&mobile_type=***&muid=***&ua=***&i=***' width='1' height='1' alt='' />
</noscript>

Do not mask or obscure the true and complete user agent, referring URL, server URL, IP address, session id, browser data, unique cookie or URL tag of an end user, or any other anonymous end user identification ascribed by you.

A detailed example follows:

<script type="text/javascript">
    var _csv = {};
    _csv['action_target'] = 'listing_profile';
    _csv['listing_id'] = '33230';
    _csv['publisher'] = 'acme';
    _csv['reference_id'] = '2';
    _csv['placement'] = 'sem_google';
    _csv['mobile_type'] = 'iphonev20';
    _csv['muid'] = '3203601234';
    _csv['ua'] = 'Mozilla/5.0%20(Windows;%20U;%20Windows%20NT%205.1;%20en-US;%20rv:1.9.0.10)%20Gecko/2009042316%20Firefox/3.0.10%20(.NET%20CLR%203.5.30729)';
    _csv['i'] = '0009000000c865034f231946f99d42656bf969b54c';
</script>
<script type="text/javascript" src="https://api.citygridmedia.com/ads/tracker/assets/api/scripts/tracker.js"></script>
<noscript>
    <img src='https://api.citygridmedia.com/ads/tracker/imp?action_target=listing_profile&listing_id=33230&publisher=acme&reference_id=2&
    placement=sem_google&mobile_type=iphonev20&muid= 3203601234&ua=Mozilla/5.0%20(Windows;%20U;%20Windows%20NT%205.1;%20en-US;%20rv:1.9.0.10)%20Gecko/2009042316%20Firefox/3.0.10%20(.NET%20CLR%203.5.30729)&i=0009000000c865034f231946f99d42656bf969b54c' width='1' height='1' alt='' />
</noscript>

Another example to demonstrate to use of the historyReferer2 parameter:

<script type="text/javascript">
    var _csv = {};
    _csv['action_target'] = 'listing_profile';
    _csv['listing_id'] = '70973';
    _csv['publisher'] = 'citysearch';
    _csv['reference_id'] = '11';
    _csv['placement'] = 'profile_page';
    _csv['historyReferer2'] = 'http://www.citysearch.com/search?what=pizza&listingId=&where=Los+Angeles%2C+CA+Metro&geoId=';
</script>
<script type="text/javascript" src="https://api.citygridmedia.com/ads/tracker/assets/api/scripts/tracker.js"></script>
<noscript>
    <img src='https://api.citygridmedia.com/ads/tracker/imp?action_target=listing_profile&listing_id=70973&publisher=citysearch&reference_id=11&
    placement=profile_page&historyReferer2=http%3A//www.citysearch.com/search%3Fwhat%3Dpizza%26listingId%3D%26where%3DLos+Angeles%252C+CA+Metro%26geoId%3D' width='1' height='1' alt='' />
</noscript>

The impression tracker should be called only once per page. Each time the tracker is called, it drops cookies which must be stored on the client and returned in the header for subsequent tracker calls.

When data is accessed using a standard browser, the browser should properly handle the cookies and no additional programming is likely needed. However, for native applications, please consult your platform SDK documentation to verify that cookies are being handled appropriately by your application. Proper cookie handling is required for your elements to be properly tracked.

Tracking Properties

The tracking properties to include in the JavaScript code are:

Parameter	Description	Required	Examples	Notes
action_target	The type of the object you are displaying	Yes	listing_profile listing_map partner_menu	See #Action Targets below
listing_id	The unique CityGrid identifier of the business or event associated with this impression	Yes	33230
reference_id	The tracking identifier for the business that you obtained from a previous webservice call	Yes	2
publisher	The publisher code that identifies you so that you get credit	Yes	acme
i	The impression_id that you receive from a previous API Call	Yes	f39cc83915414da5b1ab513d298e6f39
placement	An optional property for storing additional information you would like CityGrid Media to log on your behalf	No	sem_google sem_yahoo home_page search	An example: if you run a search engine marketing campaign for Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" — choose the values based on your needs. CityGrid will organize reports for you by placement
mobile_type	This field designates your device type name or designates the usage of our content on your Wireless Application Protocol (WAP) site	Yes for mobile publisher	wap iphonev20	For a WAP site, set the value to "wap"
muid	The hash of user phone number and/or device ID as provided by the carrier	Yes for mobile publisher	device ID phone number	Maximum of 32 characters
sourcePhone	The source phone for the click to call implementation on mobile phones	No	8878323451	Include the 10 digits for the phone number without any dashes.
dialPhone	The dialed phone for the click to call implementation on mobile phones	Yes for mobile	3124567892	Include the 10 digits for the phone number without any dashes.
ua	The client side user agent	Yes	Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.0.10) Gecko/2009042316 Firefox/3.0.10 (.NET CLR 3.5.30729)	Must be properly HTML encoded
historyReferer2	This is the url of the page that the user browses before reaching the page that fires the tracker script	No	http://www.citysearch.com/search?what=pizza&listingId=&where=Los+Angeles%2C+CA+Metro&geoId=	If this parameter is not passed, we will use document.referrer as the default historyReferer2

Action Targets

The following table lists the complete set of action targets currently available. If you have an element (page type or action) which you believe does not correspond to any of the actions described below, please contact Partner Support. Please note that it is beneficial to use non-billable actions (if applicable) for tracking, as they may become billable in the future.

Action_Target	Usage	Tracking Purpose	Billable
listing_profile	Embed on the profile page of both advertisers and non advertisers	Profile page views	Yes
click_to_call	Embed where user clicks to call provided phone number	Phone Calls	Yes
listing_profile_print	Embed on confirmation page of user printing a profile page	Profile page print	No
listing_website	Click to External Listing Website	View merchant website	Yes
listing_review	Embed anywhere reviews are shown	Review page views	Yes
write_review	Embed on confirmation page of user writing a review	Review creation	No
listing_map	Embed where a map is shown with advertiser's location	Map views	Yes
listing_driving_direction	Embed on page where directions are provided to merchant location	Views of driving directions	Yes
listing_map_print	Embed on confirmation page of user printing map of merchant location	Map printing	Yes
listing_profile_print	Embed on confirmation page of user printing merchant profile	Profile page printing	No
send_listing_email	Embed on confirmation page of user sending merchant information via email	Merchant info has been emailed	Yes
send_listing_phone	Embed on confirmation page of user sending merchant information via SMS	Merchant info has been messaged	Yes
send_listing_gps	Embed on confirmation page of user sending merchant information to GPS	Merchant info sent to GPS	No
offer	Embed on page where advertiser offer is displayed	Offer views	Yes
offer_print	Embed on confirmation page of user printing an offer	Offer printing	No
listing_request_offer	Embed on request a offer from merchant page	Offer requests	No
partner_menu	Trigger when a CityGrid menu is shown	Menu views	Yes
partner_reservation	Trigger when a CityGrid reservation window is shown	Reservation view	Yes
listing_photo	Embed on photos page	Photo view	No
upload_listing_photo	Embed on confirmation page of user uploading photo	Photo uploads	No
listing_blog	Embed on a merchant blog page	Blog page views	No
listing_forums	Embed on forums/messageboards page	Forums/messageboard page view	No
listing_newsletters	Embed on merchant newsletter page	Newletter page view	No
listing_vote	Triggered when a user votes on / rates a business listing	User votes	No
listing_correction	Embed on suggest a correction page	User suggests a listing correction	No
listing_bookmark	Click to bookmark page	Profile page has been bookmarked	No
book_appointment	External link to book an appointment	Lead Based Action	Yes
book_room	External link to book a room (e.g. at a hotel)	Lead Based Action	Yes
contact_us	External link to fill out a customized contact form (rather than generic email)	Lead Based Action	Yes
free_consultation	External link to sign up for a free consultation	Lead Based Action	Yes
free_estimate	External link to request a free estimate	Lead Based Action	Yes
online_order	External link to start an order	Lead Based Action	Yes
online_enrollment	External link to start online enrollment (e.g. in a school)	Lead Based Action	Yes
request_brochure	External link to request a brochure	Lead Based Action	Yes
request_information	External link to request more information	Lead Based Action	Yes
request_tour	External link to request a tour	Lead Based Action	Yes
request_quote	External link to request a quote	Lead Based Action	Yes
schedule_appt	External link to schedule an appointment	Lead Based Action	Yes
schedule_consult	External link to schedule a consultation	Lead Based Action	Yes
schedule_service	External link to schedule a service	Lead Based Action	Yes
view_brochure	External link to view a brochure	Lead Based Action	Yes
view_services	External link to view available services	Lead Based Action	Yes
view_inventory	External link to view inventory	Lead Based Action	Yes
virtual_tour	External link to take a virtual tour	Lead Based Action	Yes

Referral Tracking

The place data that you obtain from a CityGrid API response contains several content links to videos, reservations, menus, maps, and other types of content. You may display these links in your own applications. External links are encoded and already contain your publisher code and the corresponding reference ID within the URL. To be credited for your users following other links, you must append your publisher code and the reference ID to the links' URLs. You may also wish to append your placement identifier.

URLs which are encoded and require no modifications include website_url, menu_url, reservation_url, custom_link_3 and custom_link_4.

For example, you may see something like the following in a API response:

<location>
  <id>123456</id>
  ...
  <urls>
    <profile_url action_target="listing_profile">http://<hostname>/profile/123456/city_state/business_name.html</profile_url>
    <reviews_url action_target="listing_review">http://<hostname>/review/123456/city_state/business_name.html</reviews_url>
    <video_url action_target="video_billable">http://<hostname>/profile/video/123456/city_state/business_name.html?videoId=1834464708</video_url/>
  	<website_url action_target="listing_website">http://<hostname>/content/places/v2/click?q=ApwhFJsdfaWE</website_url>
    <menu_url action_target="partner_menu">http://<hostname>/content/places/v2/click?q=ADSFJsdfaWE</menu_url>
    <reservation_url action_target="partner_reservation">http://<hostname>/profile/reservation/123456/city_state/business_name.html</reservation_url>
    <map_url action_target="listing_map">http://<hostname>/profile/map/123456/city_state/business_name.html</map_url>
    <send_to_friend_url action_target="send_listing_email">http://<hostname>/profile/sendto/123456/city_state/business_name.html</send_to_friend_url>
  </urls>
  ...
  <reference_id>2</reference_id>
  	...
</location>

For URLs that are not encoded, you need to augment them with the given reference ID and your own information. This augmentation must be done on the on click event. In the above example, the reference ID is 2. If your publisher code is "acme" and you would like to use a placement of "home," then you would compose the following URLs for your application to navigate to the map and video URLs respectively:

http://<hostname>/profile/map/123456/city_state/business_name.html?reference_id=2&publisher=acme&placement=home

http://<hostname>/profile/video/123456/city_state/business_name.html?videoId=1834464708&reference_id=2&publisher=acme&placement=home

Encoded URLs do not require publisher, placement or reference_id attached.