/
AdGroupCriterion API

CityGrid Advertising APIs

AdGroupCriterion API

Owned by Former user (Deleted)
Last updated: May 01, 2013 by Former user (Deleted)Version comment

Introduction

The CityGrid AdGroupCriterion API is part of the Advertising API suite and allows users to add and remove categories (criteria) to and from ad groups. The ad group's place may already have associated categories; this API allows you to add additional category associations.

The terms category and criterion are used interchangeably in the Advertiser APIs. The categoryId returned from the Category API should be passed as the adGroupCriterionId to this API.

Contents

AdGroupCriterion Get Endpoint

The adgroupcriterion/get endpoint retrieves information about the adgroup-category associations. The operation is invoked via HTTPS GET to:

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

 

Request Parameters

Parameter

Description

Required

Type

Default

Example

Limit

adGroupId

The ad group whose associated categories are to be retrieved

Yes

Long

N/A

 

10 digits

keyword

The category name

No

String

N/A

Hotels & Motels

60 chars

adGroupCriterionId

The category ID (returned from the Category API)

No

Long

N/A

 

12 digits

startIndex

Page number of results to return (zero-based)

No

Integer

0

5

 

numberResults

Number of results per page

No

Integer

10

25

 

If both keyword and adgroupCriterionId are specified, the keyword parameter will be ignored.

A keyword search requires an exact match on the keyword parameter.

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: Request associations for ad group 286 for the category Birds
curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/adgroupcriterion/v2/get?adGroupId=286&keyword=Birds'
Example 2: Request associations for category 3627 for ad group 286
curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/adgroupcriterion/v2/get?adGroupId=286&adGroupCriterionId=3627'
Example 3: Request up to 20 associations category 3627 for ad group 286
curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/adgroupcriterion/v2/get?adGroupId=286&adGroupCriterionId=3627&numberResults=20'

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Total number of results

adGroupCriterions

AdGroupCriterion list

List of results

adGroupCriterion

AdGroupCriterion

Information about an AdGroup Criterion containing the following fields

adGroupId

Long

The ID of the ad group.

adGroupCriterionId

Long

The category ID (returned from the Category API)

keyword

String

The category name

type

{PRIMARY, SECONDARY}

Association type

Response Examples

Example 1: A JSON success response
{
  "totalNumEntries":3,
  "adGroupCriterions":[
    {
      "type":"PRIMARY",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      },
      "adGroupId":"30021512",
      "keyword":"Self Storage",
      "adGroupCriterionId":"6246"
    },
    {
      "type":"PRIMARY",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      },
      "adGroupId":"30021512",
      "keyword":"Household Storage",
      "adGroupCriterionId":"4242"
    },
    {
      "type":"PRIMARY",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      },
      "adGroupId":"30021512",
      "keyword":"Storage",
      "adGroupCriterionId":"4233"
    }
  ]
}
Example 2: An XML success response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>1</totalNumEntries>
  <adGroupCriterions>
    <adGroupCriterion>
      <adGroupCriterionId>4295</adGroupCriterionId>
      <adGroupId>286</adGroupId>
      <keyword>Hotels &amp; Motels</keyword>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
      <type>PRIMARY</type>
      </adGroupCriterion>
  </adGroupCriterions>
</results>
Example 3: A JSON missing parameter response

A request to api.citygrid.com/advertising/adgroupcriterion/v2/get?keyword=Birds returns a response such as:

{
  "totalNumEntries":1,
  "adGroupCriterions":[
    {
      "type":"",
      "response":{
        "field":"adGroupId",
        "message":"The parameter adGroupId is required but has not been supplied",
        "code":"PARAMETER_REQUIRED"
      },
      "adGroupId":"",
      "keyword":"",
      "adGroupCriterionId":""
    }
  ]
}
Example 4: No criterion found (XML response)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>1</totalNumEntries>
  <adGroupCriterions>
    <adGroupCriterion>
      <adGroupCriterionId></adGroupCriterionId>
      <adGroupId></adGroupId>
      <keyword></keyword>
      <response>
        <code>ENTITY_NOT_FOUND</code>
        <field></field>
        <message>The AdGroupCriterion could not be found</message>
      </response>
      <type></type>
    </adGroupCriterion>
  </adGroupCriterions>
 </results>

AdGroupCriterion Mutate Endpoint

The adgroupcriterion/mutate endpoint allows adgroup-category associations to be created and removed using the ADD and REMOVE operation keywords, respectively.

These operations are invoked via HTTPS POST to:

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

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

Request Parameters

Every adgroupcriterion/mutate request requires the following two parameters:

Property

Type

Description

Required

operator

{ADD, REMOVE}

Type of operation to perform (case sensitive)

Yes

operand

AdGroupCriterion(s)

The association(s) to operate on

Yes

The properties of an adgroupcriterion object in a request are:

Parameter

Description

Required

Type

Default

Example

Limit

adGroupId

ID of the ad group

Yes

Long

N/A

1722

10 digits

type

Association type, 1=PRIMARY, 2=SECONDARY

No

Integer

1

1

1 digit

adGroupCriterionId

The category ID (returned from the Category API)

Yes

Long

N/A

 

12 digits

Request Header Values

Header

Description

Required

Valid Values

Content-Type

Media type of the request body, if any

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: Add categories 883 and 1722 and remove category 14 from ad group 998
{
  "mutateOperationListResource":[
    {
      "operator":"ADD",
      "operand":{
        "adGroupId":"998",
        "adGroupCriterionId":"883"
      }
    },
    {
      "operator":"REMOVE",
      "operand":{
        "adGroupId":"998",
        "adGroupCriterionId":"14"
      }
    },
    {
      "operator":"ADD",
      "operand":{
        "adGroupId":"998",
        "adGroupCriterionId":"1722"
      }
    }
  ]
}
Example 2: Remove category 1722 from ad group 17 and add category 808 to ad group 5581
<mutateOperationListResource>
  <mutateOperation>
    <operand>
       <adGroupId>17</adGroupId>
       <adGroupCriterionId>1722</adGroupCriterionId>
    </operand>
    <operator>REMOVE</operator>
  </mutateOperation>
  <mutateOperation>
    <operand>
       <adGroupId>17</adGroupId>
       <adGroupCriterionId>808</adGroupCriterionId>
    </operand>
    <operator>ADD</operator>
  </mutateOperation>
</mutateOperationListResource>

Response Properties

Property

Type

Description

Limit

response

Response Metadata

(See complete response descriptions)

10 digits

totalNumEntries

Integer

Total number of associations returned

60 chars

adGroupCriterions

AdGroupCriterion list

The returned associations

12 digits

adGroupCriterion

AdGroupCriterion

An association affected by the operation

 

keyword

String

The category linked to the ad group

 

type

{PRIMARY, SECONDARY}

Association type

 

Response Examples

Example 1: A JSON success response
{
  "totalNumEntries":1,
  "adGroupCriterions":[
    {
      "type":"PRIMARY",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      },
      "adGroupId":"286",
      "keyword":"Hotels & Motels",
      "adGroupCriterionId":"4295"
    }
  ]
}
Example 2: An XML success response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>3</totalNumEntries>
  <adGroupCriterions>
    <adGroupCriterion>
      <adGroupCriterionId>1722</adGroupCriterionId>
      <adGroupId>2</adGroupId>
      <keyword>Restaurants</keyword>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
      <type>PRIMARY</type>
    </adGroupCriterion>
    <adGroupCriterion>
      <adGroupCriterionId>1722</adGroupCriterionId>
      <adGroupId>2</adGroupId>
      <keyword>Restaurants</keyword>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
      <type>PRIMARY</type>
    </adGroupCriterion>
    <adGroupCriterion>
      <adGroupCriterionId>1722</adGroupCriterionId>
      <adGroupId>2</adGroupId>
      <keyword>Restaurants</keyword>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
      <type>SECONDARY</type>
    </adGroupCriterion>
  </adGroupCriterions>
</results>
Example 3: A JSON error response (missing required parameter)
{
  "totalNumEntries":1,
  "adGroupCriterions":[
    {
      "type":"",
      "response":{
        "field":"AdGroupId",
        "message":"The parameter, AdGroupId, is required but has not been supplied.",
        "code":"PARAMETER_REQUIRED"
      },
      "adGroupId":"",
      "keyword":"",
      "adGroupCriterionId":""
    }
  ]
}
Example 4: An XML error response (missing required parameter)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>1</totalNumEntries>
  <adGroupCriterions>
    <adGroupCriterion>
      <adGroupCriterionId/>
      <adGroupId/>
      <keyword/>
      <response>
        <field>AdGroupId</field>
        <code>PARAMETER_REQUIRED</code>
        <message>The parameter adGroupId is required but has not been supplied</message>
      </response>
      <type/>
    </adGroupCriterion>
  </adGroupCriterions>
</results>