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="http://api.citygridmedia.com/ads/tracker/assets/api/scripts/tracker.js"></script>
<noscript>
    <img src='http://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="http://api.citygridmedia.com/ads/tracker/assets/api/scripts/tracker.js"></script>
<noscript>
    <img src='http://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>

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:

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.

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.