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 HTTPS services to fetch pre-rendered mobile ads via either:

An HTTPS request through a URL, which is convenient for native mobile apps.
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 HTTPS request to a URL and receive ad data in XML or JSON, including a link to an image.

HTTPS Endpoint

The following endpoint is used with HTTPS GET:

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

Request

The mobile banner ad search accepts the following query parameters:

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.	mobile-001-320x50 mobile-003-300x250
what	What a user is searching for. For multi-word searches, simply put a space between the words.	Yes		pizza sporting%20goods 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 term if available.	No		italian%20food plumbing%20work
raw_where	The original user search term if available.	No		los%20angeles
format	The desired format for the results. The default format is xml.	No	xml json	json
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
muid	The hash of user phone number and/or device ID as provided by the carrier. Maximum of 32 characters.	Yes	device ID phone number	2054538217
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

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
- https://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
- https://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:

Element	Description	Parent Element	Attributes
ads	Top level container of advertisement elements.
ad	Advertisement data.	ads	id - The ID to uniquely identify the ad
impression_id	The impression ID returned per ad.	ad
ad_image_url	The URL where the image resides. See note below.	ad
listingId	The ID that uniquely identifies a CityGrid business.	ad
ad_destination_url	URL of the ad click.	ad

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

<?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:

JSON

{
    "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 HTTPS status will be set to 403, as described in the table below:

HTTPS Status Code	Type	Message	Description
403	Status report	publisher is a required field.	Access is forbidden because of a missing publisher property.
403	Status report	collection_id is a required field.	Access is forbidden because of a missing collection_id property.
403	Status report	what is a required field.	Access is forbidden because of a missing what parameter.
403	Status report	either where or lat/lon is required.	Access is forbidden because of missing location information (where or lat and lon).
403	Status report	muid is a required field.	Access is forbidden because of a missing muid parameter.
403	Status report	Invalid publisher parameter	Access is forbidden because of an invalid publisher property.
403	Status report	Invalid collection_id parameter	Access is forbidden because of an invalid collection_id property.
403	Status report	max must be between 1-10.	Access is forbidden because of an invalid max property.

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.

Properties Name	Description	Required	Valid Values	Example
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.	mobile-001-320x50 mobile-003-300x250
width	The width of the ad slot. Pass the width of the ad space not the image size you expect.	Yes	An integer in pixels.	300
height	The height of the ad slot. Pass the height of the ad space not the image size you expect.	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 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, CA 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 term if available.	No		italian food plumbing work
raw_where	The original user search term if available.	No		los angeles
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
serve_url	This property is only required if the web ads is called within an iframe. This property stands for the url of the page that the ad is serving on.	No	Unescaped URL	http://losangeles.citysearch.com/profile/45654239/los_angeles_ca/green_door.html

Errors

Errors are indicated in the HTTPS response as follows:

HTTPS Status Code	Type	Message	Description
403	Status report	publisher is a required field.	Access is forbidden because of a missing publisher property.
403	Status report	collection_id is a required field.	Access is forbidden because of a missing collection_id property.
403	Status report	what is a required field.	Access is forbidden because of a missing what parameter.
403	Status report	either where or lat/lon is required.	Access is forbidden because of missing location information (where or lat and lon).
403	Status report	Invalid publisher parameter	Access is forbidden because of an invalid publisher property.
403	Status report	Invalid collection_id parameter	Access is forbidden because of an invalid collection_id property.
403	Status report	max must be between 1-10.	Access is forbidden because of an invalid max property.

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:

Browser not supported