Skip to end of metadata
Go to start of metadata

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:

  1. An HTTPS 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.

Icon

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:

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

Icon

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.

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

 

Icon

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.

Icon

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

JSON Response

The following is an example of a JSON response:

JSON

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:

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.

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.

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:

  • No labels