Mobile Ads API
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 |
what | What a user is searching for. For multi-word searches, simply put a space between the words. | Yes |
| pizza |
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 |
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 |
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 |
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 | 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. | No |
| google |
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 |
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
- Obtain at most 4 small iPhone ads for autos in Seattle
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 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 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 |
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 |
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 |
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 |
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. | No |
| google |
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. |
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. |
mobile-007-300x50 | Category-based ads. This collection contains a set of templates with |
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. |
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. |
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. |
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:
