AdGroupAd API

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:

api.citygrid.com/advertising/adgroupad/v2/get

Input data such as request parameters are subject to field size limits.

Request Parameters

Parameter	Description	Required	Type	Default	Example
`adId`	Specified to retrieve ads by id, optionally includes the ad type. If provided other parameters are ignored.	Only if `campaignId` and `adGroupId` are missing	Long	type defaults to PERFORMANCE	38497671,38497622;PERFORMANCE
`adGroupId`	Specified to retrieve ads by ad group(s). If provided campaign id is ignored.	Only if `campaignId` and `adId` are missing	Long list (comma-separated)	N/A	5482,5483
`campaignId`	Specified to retrieve ads by ACTIVE campaign(s)	Only if `adGroupId` and `adId` are missing	Long list (comma-separated)	N/A	1234,1404
`startIndex`	Page number of results to return (zero-based)	No	Integer	0	5
`numberResults`	Number of results per page	No	Integer	10	25

If retrieving by campaign ID, only active campaigns may be specified.

Request Header Values

Header	Description	Required	Valid Values
`Accept`	Requested format for the response	Yes	`application/json` `application/xml`
`authToken`	Authentication token from the Authentication API	Yes	Valid token
`developerToken`	The token received during registration	Yes	Valid token

Request Examples

Example 1: Get up to 3 ads in campaigns 123 and 666

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:mydevtoken' \
    'https://api.citygrid.com/advertising/adgroupad/v2/get?campaignId=123,666&numberResults=3'

Example 2: Get the default number of ads in ad groups 286, 325, and 287

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:mydevtoken' \
    'https://api.citygrid.com/advertising/adgroupad/v2/get?adGroupId=286,325,287'

Example 3: Get ads 786 and 512 in XML

curl -X GET \
    -H 'Accept:application/xml' \
    -H 'authToken:mytoken' \
    -H 'developerToken:mydevtoken' \
    'https://api.citygrid.com/advertising/adgroupad/v2/get?adId=786,512'

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`totalNumEntries`	Integer	Number of ads returned
`adGroupAds`	Ad list	List of ads returned
`adGroupAd`	Ad	Content of the ad
`adGroupId`	Long	The ID of the ad group containing the ad
`id`	Long	The ID of the ad
`adType`	String	The Ad type, e.g., PERFORMANCE_AD
`status`	{ACTIVE,DISABLE}	Ad status
`tagline`	String	The Ad tagline
`imageUrl`	String	URL from where the ad image can be retrieved (max dimensions: 100x100)
`websiteUrl`	String	URL to which the ad directs, if the place is virtual; otherwise blank

Response Examples

Example 1: A JSON success response

{
  "totalNumEntries": 1,
  "adGroupAds": [
    {
      "adGroupId": "5482",
      "id": "42150701",
      "adType": "PERFORMANCE_AD",
      "status": "ACTIVE",
      "tagline": "Massimino's, where the locals dine.",
      "imageUrl": "",
      "websiteUrl": "",
      "response": {
        "field": "",
        "message": "Success",
        "code": "SUCCESS"
      }
    }
  ]
}

Example 2: An XML success response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>1</totalNumEntries>
  <adGroupAds>
    <adGroupAd>
      <adGroupId>5482</adGroupId>
      <id>42150701</id>
      <adType>PERFORMANCE_AD</adType>
      <status>ACTIVE</status>
      <tagline>Massimino's, where the locals dine.</tagline>
      <imageUrl/>
      <websiteUrl/>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupAd>
  </adGroupAds>
</results>

Example 3: JSON success response for a virtual place

{
  "totalNumEntries": 1,
  "adGroupAds": [
    {
      "adGroupId": "107",
      "id": "99062562",
      "adType": "PERFORMANCE_AD",
      "status": "ACTIVE",
      "tagline": "myTagline1",
      "imageUrl": "http://www.citygridmedia.com/wp-content/themes/default/images/cs_logo.png",
      "websiteUrl": "example.com",
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ]
}

Example 4: No data for the campaign specified in the search criteria (JSON response)

{
  "totalNumEntries":0,
  "adGroupAds": [
    {
      "adGroupId": "",
      "id": "",
      "adType": "",
      "status": "",
      "tagline": "",
      "imageUrl": "",
      "websiteUrl": "",
      "response": {
        "field": "",
        "message": "There is no data for campaignId 1324567",
        "code": "DATA_NOT_FOUND"
      }
    }
  ]
}

Example 5: No data for the campaign specified in the search criteria (XML response)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>0</totalNumEntries>
  <adGroupAds>
    <adGroupAd>
      <adGroupId/>
      <id/>
      <adType/>
      <status/>
      <tagline/>
      <imageUrl/>
      <websiteUrl/>
      <response>
        <field/>
        <code>DATA_NOT_FOUND</code>
        <message>There is no data for campaignId 1324567</message>
      </response>
    </adGroupAd>
  </adGroupAds>
</results>

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:

api.citygrid.com/advertising/adgroupad/v2/mutate

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
`operator`	{ADD, REMOVE, SET}	Type of operation to perform (case sensitive)	Yes
`operand`	AdGroupAd	The ad to operate on	Yes

The properties of an adgroupad object in a request are:

Property	Description	Type	Required
`adGroupId`	The id of the ad group to which the ad belongs	Long	If operator is ADD. Deprecated for SET and REMOVE.
`ad`	Content of the ad	Ad	If operator is ADD

The properties of an ad object are:

Property	Description	Required	Type	Default	Limit
`id`	ID of the ad	If SET or REMOVE	Long	N/A	10 digits
`type`	The ad type	No	{PERFORMANCE_AD}	PERFORMANCE_AD
`tagline`	The ad tagline	If ADD	String	N/A	140 chars
`imageUrl`	URL of the ad image	No	String	N/A	2000 chars
`websiteUrl`	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
`Content-Type`	Media type of the request body	Yes	`application/json` `application/xml`
`Accept`	Requested format for the response	Yes	`application/json` `application/xml`
`authToken`	Authentication token from the Authentication API	Yes	Valid token
`developerToken`	The token received during registration	Yes	Valid token

Request Examples

Example 1: Create an ad group ad (JSON)

{
  "mutateOperationListResource": [
    {
      "operator": "ADD",
      "operand": {
        "adGroupId": "2861",
        "ad": {
          "type": "PERFORMANCE_AD",
          "tagline": "myTagline",
          "imageUrl": "http://www.citygridmedia.com/wp-content/themes/default/images/cs_logo.png"
        }
      }
    }
  ]
}

Example 2: Create an ad group ad (XML)

<mutateOperationListResource>
  <mutateOperation>
    <operand>
      <adGroupId>107</adGroupId>
      <ad>
        <type>PERFORMANCE_AD</type>
        <imageUrl>http://www.citygridmedia.com/wp-content/themes/default/images/cs_logo.png</imageUrl>
      </ad>
    </operand>
    <operator>ADD</operator>
  </mutateOperation>
</mutateOperationListResource>

Example 3: Create an ad for a virtual place (JSON)

{
  "mutateOperationListResource":[
    {
      "operator":"ADD",
      "operand":{
        "adGroupId":"107",
        "ad":{
          "type":"PERFORMANCE_AD",
          "tagline":"myTagline",
          "websiteUrl":"fishmarket.com",
          "imageUrl":"http://www.citygridmedia.com/wp-content/themes/default/images/cs_logo.png"
        }
      }
    }
  ]
}

Example 4: Update an ad (JSON)

{
  "mutateOperationListResource": [
    {
      "operator": "SET",
      "operand": {
        "adGroupId": "107",
        "ad": {
          "id": "86780772",
          "type": "PERFORMANCE_AD",
          "tagline": "new Tagline",
          "imageUrl": "http://www.citygridmedia.com/wp-content/themes/default/images/cs_logo.png"
        }
      }
    }
  ]
}

Example 5: Delete an AdGroup-Ad association (JSON)

{
  "mutateOperationListResource": [
    {
      "operator": "REMOVE",
      "operand": {
        "adGroupId": "107",
        "ad": {
          "id": "86780772"
        }
      }
    }
  ]
}

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`adGroupAds`	Ad list	List of AdGroupAds
`adGroupAd`	Ad	Information on an adgroup-ad association
`adGroupId`	Long	ID of the ad group containing the Ad
`id`	Long	ID of the ad group Ad
`adType`	String	The type of the ad
`status`	String	The status of the ad
`tagline`	String	Ad Tagline
`imageUrl`	String	URL from where the ad image can be retrieved
`websiteUrl`	String	URL to which the ad directs, if the place is virtual; otherwise blank

Response Examples

Example 1: A JSON success response

{
  "adGroupAds": [
    {
      "adGroupId": "",
      "id": "42150701",
      "adType": "PERFORMANCE_AD",
      "status": "DISABLE",
      "tagline": "Massimino's, where the locals dine.",
      "websiteUrl": "",
      "imageUrl": "",
      "response": {
        "field": "",
        "message": "Success",
        "code": "SUCCESS"
      }
    }
  ]
}

Example 2: An XML success response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <adGroupAds>
    <adGroupAd>
      <adGroupId>2861</adGroupId>
      <id>85200852</id>
      <adType>PERFORMANCE_AD</adType>
      <status>ACTIVE</status>
      <tagline>myTagline</tagline>
      <imageUrl/>
      <websiteUrl/>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroupAd>
  </adGroupAds>
</results>

Example 3: A JSON success response for a virtual place

{
  "adGroupAds":[
    {
      "adGroupId":"107",
      "id":"100810422",
      "adType":"PERFORMANCE_AD",
      "status":"ACTIVE",
      "tagline":"myTagline",
      "imageUrl":"http://www.citygridmedia.com/wp-content/themes/default/images/cs_logo.png",
      "websiteUrl":"fishmarket.com",
      "response":{
        "code":"SUCCESS",
        "message":"Success",
        "field":""
      }
    }
  ]
}

Example 4: A JSON error response

{
  "adGroupAds": [
    {
      "adGroupId": "2861",
      "id": "",
      "adType": "",
      "status": "",
      "tagline": "",
      "imageUrl": "",
      "websiteUrl": "",
      "response": {
        "field": "",
        "message": "The ad could not be found",
        "code": "ENTITY_NOT_FOUND"
      }
    }
  ]
}

Example 5: An XML error response

<results>
  <adGroupAds>
    <adGroupAd>
      <adGroupId>9074931</adGroupId>
      <id/>
      <adType/>
      <status/>
      <tagline/>
      <imageUrl/>
      <websiteUrl/>
      <response>
        <field/>
        <code>ENTITY_NOT_FOUND</code>
        <message>The ad could not be found</message>
      </response>
    </adGroupAd>
  </adGroupAds>
</results>