...
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 HTTPS services to fetch pre-rendered mobile ads via either:
- An HTTP HTTPS request through a URL, which is convenient for native mobile apps.
- JavaScript and HTML code, which is convenient for mobile web apps.
...
| Info |
|---|
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
| Table of 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.
...
If you are developing a mobile application, you can make a direct HTTP 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 HTTP HTTPS GET:
| Code Block |
|---|
httphttps://api.citygridmedia.com/ads/mobile/v2/banner |
...
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 |
...
- Obtain a medium-sized ad for restaurants in Los Angeles
- Obtain at most 4 small iPhone ads for autos in Seattle
...
The following is an example of a JSON response:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"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 HTTPS status will be set to 403, as described in the table below:
HTTP 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. |
...
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.
| Code Block |
|---|
<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.
| Code Block |
|---|
<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>
|
...
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 are indicated in the HTTP HTTPS response as follows:
HTTP 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. |
...
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.
...