Introduction

As a CityGrid partner, you can publish CityGrid advertisements on your mobile applications (both web and native), and get paid when your users interact with them. The CityGrid Mobile Ads API provides HTTP services to fetch pre-rendered mobile ads via either:

1. An HTTP request through a URL, which is convenient for native mobile apps.
2. JavaScript and HTML code, which is convenient for mobile web apps.

This document explains how to display CityGrid ad units for either type of mobile application.

If you are looking to display pre-rendered ads for classic (i.e., desktop) web applications, see the Web Ads API. If you are interested in obtaining raw ad data from which you render your own ads, see the Custom Ads API.

Contents

Audience

The Mobile Ads API is intended for developers of mobile applications who want place advertisements from CityGrid into their applications to earn credit when the advertisement is clicked.

Version 2 Updates

The mobile banner webservice is currently at Version 2. There are two notable changes since Version 1:

• The impression_id parameter has been added.
• The ad_destination_url now contains an obfuscated URL. The click to the obfuscated URL will undergo decryption and redirect to the destination URL.

Obtaining Mobile Banner Ads in XML or JSON

If you are developing a mobile application, you can make a direct HTTP request to a URL and receive ad data in XML or JSON, including a link to an image.

HTTP Endpoint

The following endpoint is used with HTTP GET:

http://api.citygridmedia.com/ads/mobile/v2/banner

Request

The mobile banner ad search accepts the following query parameters:

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

Usage Examples

The following are examples of ad requests for sample publisher and muid values. You may click on the links to try them out.

• Obtain a medium-sized ad for restaurants in Los Angeles
  • http://api.citygridmedia.com/ads/mobile/v2/banner?publisher=test&where=los+angeles&what=restaurant&muid=8943&collection_id=mobile-003-300x250
• Obtain at most 4 small iPhone ads for autos in Seattle
  • http://api.citygridmedia.com/ads/mobile/v2/banner?publisher=test&where=seattle&what=auto&muid=8943&collection_id=mobile-001-320x50&max=4

Response

The Mobile Ads results can be returned in either XML or JSON format.

The following table describes the return elements:

The image results are returned as an "image/png" response. The image is rendered by CityGrid, and contains information as business name, review rating, number of reviews and distance.

Character data will be escaped as necessary, so you will often see character entities for ", &, >, <, and '.

XML Response

The following is an example of an XML response:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<ads>
  <ad id="59886932">
    <listing_id>32895961</listing_id>
    <ad_destination_url>
      http://pfpc.citygridmedia.com/pfp/ad/v2?q=JKA_CPlD7kF2Zbqb...x87io-IfDI
    </ad_destination_url>
    <ad_image_url>
      http://banners.citygridmedia.com/mobileimages?W4d09-V3GJ...nxt0mjn-Q
    </ad_image_url>
    <impression_id>00c4050008b8b6fdb3eb3c463ab3fdcc5b04f6ad13</impression_id>
  </ad>
</ads>

JSON Response

The following is an example of a JSON response:

{
    "ads": [{
        "id": "59886932",
        "listingId": 32895961,
        "adDestinationUrl": "http://pfpc.citygridmedia.com/pfp/ad/v2?q=JKA_CPlD7kF2Zbqb...x87io-IfDI",
        "adImageUrl": "http://banners.citygridmedia.com/mobileimages?W4d09-V3GJ...nxt0mjn-Q",
        "impressionId": "25c4050008b8b6fdb3eb39963ab3fdcc5b04f6ad13"
    }]
}

Errors

If errors occur, the HTTP status will be set to 403, as described in the table below:

Obtaining Mobile Ads via JavaScript and HTML

If you are building an application that is designed to run on the mobile web, then you can take advantage of the CityGrid loader, which uses JavaScript to directly add an add to an HTML page through DOM manipulation.

To enable ads to be displayed in this fashion, you must include the loader script in your HTML page as follows:

<script type="text/javascript" src="http://static.citygridmedia.com/ads/scripts/v2/loader.js"></script>

To obtain the actual ad, invoke the CityGrid.MobileAds constructor with two arguments: the id of the div element that wraps the ad unit, and a JavaScript object that holds the ad parameters.

<script type="text/javascript">
  new CityGrid.MobileAds(containerDiv, callParameters);
</script>

The ad image will be rendered into your div. The following example adds an ad to a div with the id of sidebar_ad_slot, and ad parameters that specify an ad relevant for sushi and a given longitude and latitude.

<div id="ad_slot"></div>
<script type="text/javascript" src="http://static.citygridmedia.com/ads/scripts/v2/loader.js"></script>
<script type="text/javascript">
  new CityGrid.MobileAds('ad_slot', {
    collection_id: 'mobile-001-320x50',
    publisher: 'citysearch',
    what: 'sushi',
    where: '90069',
    lat: 34.088188,
    lon: -118.37205,
    width: 320,
    height: 50
  });
</script>

Ad Parameters

The following is the complete set of JavaScript properties for the parameters object.

Errors

Errors are indicated in the HTTP response as follows:

Collection IDs

The collection_id property allows you rotate different themes to change the look-and-feel of the ad. Examples of collection IDs include:

CollectionId	Description
mobile-001-320x50	This collection holds a single generic template. For hd version please use mobile-004-320x50.
mobile-002-300x50	This collection holds a single generic template.
mobile-003-300x250
mobile-004-320x50	For ad samples please refer to collection mobile-001-320x50. This collection contains the same templates as mobile-001-320x50 but with higher resolution.
mobile-005-300x250	Category-based ad. This collection contains a set of templates with different themes and will use the one best matched the user search term. Generic Automotive Sales & Services Food & Dining Health & Medical Services Shopping Travel Home & Garden Personal Services
mobile-006-320x50	Category-based ads. This collection contains a set of templates with different themes and will use the one best matched the user search term. For hd version please use mobile-008-320x50. Generic Food & Dining Automotive Sales & Services Health & Medical Services Shopping Travel   Home & Garden Personal Service
mobile-007-300x50	Category-based ads. This collection contains a set of templates with different themes and will use the one best matched the user search term. Generic Food & Dining Automotive Sales & Services Health & Medical Services Shopping Travel Home & Garden Personal Services
mobile-008-320x50	Please refer to mobile-006-320x50. This collection contains the same templates as mobile-006-320x50 but with higher resolution.
mobile-009-216x36	Category-based ads. This collection contains a set of templates with different themes and will use the one best matched the user search term. Generic Food & Dining Automotive Sales & Services Health & Medical Services Shopping Travel Home & Garden Personal Services
mobile-010-360x480	Category-based ads. This collection contains a set of templates with different themes and will use the one best matched the user search term. Generic Food & Dining Automotive Sales & Services Health & Medical Services Shopping Travel Home & Garden Personal Services
mobile-011-720x90	Category-based ads. This collection contains a set of templates with different themes and will use the one best matched the user search term. Generic Food & Dining Automotive Sales & Services Health & Medical Services Shopping Travel Home & Garden Personal Services

House Ads

If an ad request cannot be satisfied, a house advertisement image is returned. The API randomly selects one house ad from those available for the collection ID supplied.

The following advertisement is an example of house ads for collection ID mobile-001-320x50: