Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

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

Icon

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
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

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
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:

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)
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

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
Example 2: An XML success response
Example 3: A JSON success response for a virtual place
Example 4: A JSON error response
Example 5: An XML error response
  • No labels