Introduction
The CityGrid AdGroupAd API is part of the Advertising API suite and allows users to manage the ads associated with an ad group.
Contents
AdGroupAd Get Endpoint
The adgroupad/get endpoint retrieves information about ads that meet certain search criteria. The operation is invoked via HTTPS GET to:
|
Input data such as request parameters are subject to field size limits.
Request Parameters
Parameter | Description | Required | Type | Default | Example |
|---|---|---|---|---|---|
| Specified to retrieve ads by id, optionally includes the ad type. If provided other parameters are ignored. | Only if | Long | type defaults to PERFORMANCE | 38497671,38497622;PERFORMANCE |
| Specified to retrieve ads by ad group(s). If provided campaign id is ignored. | Only if | Long list (comma-separated) | N/A | 5482,5483 |
| Specified to retrieve ads by ACTIVE campaign(s) | Only if | Long list (comma-separated) | N/A | 1234,1404 |
| Page number of results to return (zero-based) | No | Integer | 0 | 5 |
| Number of results per page | No | Integer | 10 | 25 |
Request Header Values
Header | Description | Required | Valid Values |
|---|---|---|---|
| Requested format for the response | Yes |
|
| Authentication token from the Authentication API | Yes | Valid token |
| The token received during registration | Yes | Valid token |
Request Examples
Example 1: Get up to 3 ads in campaigns 123 and 666
Example 2: Get the default number of ads in ad groups 286, 325, and 287
Example 3: Get ads 786 and 512 in XML
Response Properties
Property | Type | Description |
|---|---|---|
| Response Metadata | |
| Integer | Number of ads returned |
| Ad list | List of ads returned |
| Ad | Content of the ad |
| Long | The ID of the ad group containing the ad |
| Long | The ID of the ad |
| String | The Ad type, e.g., PERFORMANCE_AD |
| {ACTIVE,DISABLE} | Ad status |
| String | The Ad tagline |
| String | URL from where the ad image can be retrieved (max dimensions: 100x100) |
| String | URL to which the ad directs, if the place is virtual; otherwise blank |
Response Examples
Example 1: A JSON success response
Example 2: An XML success response
Example 3: JSON success response for a virtual place
Example 4: No data for the campaign specified in the search criteria (JSON response)
Example 5: No data for the campaign specified in the search criteria (XML response)
AdGroupAd Mutate Endpoint
The adgroup/mutate endpoint allows ads to be created, modified, or deleted using the ADD, SET, and REMOVE operation keywords, respectively.
These operations are invoked via HTTPS POST to:
|
Input data such as request parameters are subject to field size limits.
Request Parameters
Every adgroupad/mutate request requires the following two parameters:
Property | Type | Description | Required |
|---|---|---|---|
| {ADD, REMOVE, SET} | Type of operation to perform (case sensitive) | Yes |
| AdGroupAd | The ad to operate on | Yes |
The properties of an adgroupad object in a request are:
Property | Description | Type | Required |
|---|---|---|---|
| The id of the ad group to which the ad belongs | Long | If operator is ADD. Deprecated for SET and REMOVE. |
| Content of the ad | Ad | If operator is ADD |
The properties of an ad object are:
Property | Description | Required | Type | Default | Limit |
|---|---|---|---|---|---|
| ID of the ad | If SET or REMOVE | Long | N/A | 10 digits |
| The ad type | No | {PERFORMANCE_AD} | PERFORMANCE_AD | |
| The ad tagline | If ADD | String | N/A | 140 chars |
| URL of the ad image | No | String | N/A | 2000 chars |
| URL to which the ad redirects, only if the place is virtual. | Yes if ADD and only for businesses marked virtual, otherwise prohibited. | String | N/A | 2000 chars |
Request Header Values
Header | Description | Required | Valid Values |
|---|---|---|---|
| Media type of the request body | Yes |
|
| Requested format for the response | Yes |
|
| Authentication token from the Authentication API | Yes | Valid token |
| The token received during registration | Yes | Valid token |
Request Examples
Example 1: Create an ad group ad (JSON)
Example 2: Create an ad group ad (XML)
Example 3: Create an ad for a virtual place (JSON)
Example 4: Update an ad (JSON)
Example 5: Delete an AdGroup-Ad association (JSON)
Response Properties
Property | Type | Description |
|---|---|---|
| Response Metadata | |
| Ad list | List of AdGroupAds |
| Ad | Information on an adgroup-ad association |
| Long | ID of the ad group containing the Ad |
| Long | ID of the ad group Ad |
| String | The type of the ad |
| String | The status of the ad |
| String | Ad Tagline |
| String | URL from where the ad image can be retrieved |
| String | URL to which the ad directs, if the place is virtual; otherwise blank |