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

Places that Pay

Owned by Former user (Deleted)
Last updated: Sept 29, 2014

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

historyReferer2This is the url of the page that the user browses before reaching the page that fires the tracker scriptNohttp://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 appointmentLead Based ActionYes
book_roomExternal link to book a room (e.g. at a hotel)Lead Based ActionYes
contact_usExternal link to fill out a customized contact form (rather than generic email)Lead Based ActionYes
free_consultationExternal link to sign up for a free consultationLead Based ActionYes
free_estimateExternal link to request a free estimateLead Based ActionYes
online_orderExternal link to start an orderLead Based ActionYes
online_enrollmentExternal link to start online enrollment (e.g. in a school)Lead Based ActionYes
request_brochureExternal link to request a brochureLead Based ActionYes
request_informationExternal link to request more informationLead Based ActionYes
request_tourExternal link to request a tourLead Based ActionYes
request_quoteExternal link to request a quoteLead Based ActionYes
schedule_apptExternal link to schedule an appointmentLead Based ActionYes
schedule_consultExternal link to schedule a consultation Lead Based ActionYes
schedule_serviceExternal link to schedule a serviceLead Based ActionYes
view_brochureExternal link to view a brochureLead Based ActionYes
view_servicesExternal link to view available servicesLead Based ActionYes
view_inventoryExternal link to view inventoryLead Based ActionYes
virtual_tourExternal link to take a virtual tourLead Based ActionYes

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.