Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid Campaign API is part of the Advertising API suite and enables developers to write applications to manage campaigns. A campaign holds one or more ad groups together with a budget and serving date range. The API provides two endpoints: campaign/get and campaign/mutate.

Contents

Campaign Get Endpoint

The campaign/get endpoint retrieves information about one or more selected campaigns. The operation is invoked via HTTPS GET to:

Request Parameters

Parameter

Description

Required

Type

Default

Example

campaignId

Comma-separated list of campaign IDs. If specified, other filter parameters will be ignored.

No

Long

1,2,3,4,5

externalId

Comma-separated list of external IDs of the campaign. If specified without campaignId, other filter parameters will be ignored.

No

Long

6,7,8,9,10

campaignStatus

Case-sensitive list of statuses for filtering

No

{ACTIVE, CANCELLED, PENDING, SUSPENDED}

ACTIVE

startDate

Restricts campaigns to those starting on or after this date. This date refers to the date the creator of the campaign indicated that the campaign should start, not necessarily the date the campaign actually started.

No

String

20100131

endDate

Restricts campaigns to those ending on or before this date. If the field is omitted, campaigns for all end dates are returned.

No

String

20100131

ordering

Field(s) to sort by

No

{name, date}

name

sortAsc

Used with ordering to determine ascending or descending sort

No

{true, false}

false

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 campaignId appears, then all other parameters will be ignored.

Icon

If externalId appears and campaignId does not appear, then all other parameters will be ignored.

Request Headers

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 campaigns 1, 54, 766, and 5678
Example 2: Get all campaigns in a date range for the current user's account, 8 campaigns per page, ordered ascending by name
Example 3: Get campaigns with external ids 1 and 2
Example 4: Get all active campaigns for the current user's account

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Total number of campaigns in the response

totalBudget

Double

Total monthly budget for the campaigns listed

totalDailyBudget

Double

Total daily budget for the campaigns listed

campaigns

Campaign List

The campaigns returned from the search

id

String

The campaign ID

name

String

Arbitrary campaign name, not shown in the ads

servingStatus

{ACTIVE, CANCELLED, PENDING,
SUSPENDED}

Status of the campaign in the system

startDate

Datestring

Date that the creator of the campaign indicated the campaign should begin, YYYYMMDD format

endDate

Datestring

Date that the campaign ends if any, YYYYMMDD format

cancelDate
Datestring

Date when campaign should no longer be in distribution. cancelDate is set to following day in YYYYMMDD format when REMOVE operation is called.

It is empty when it is not on cancelled or pending cancellation state

budgetAmount

Double

Current budget for campaign, in U.S. Dollars

period

{DAILY, MONTHLY}

Period over which to spend the budget

externalId

Long

External ID of the campaign

affiliateIdIntegerAffiliate ID of the campaign

Response Examples

Example 1: A XML success response
Example 2: A JSON success response

Campaign Mutate Endpoint

The campaign/mutate endpoint uses five operators to provide the following operations on campaigns:

  • The ADD operator creates a campaign.
  • The SET operator updates campaign properties.
  • The PAUSE operator pauses a campaign
  • The UNPAUSE operator re-activates a campaign
  • The REMOVE operator cancels a campaign.

These operations are invoked via HTTPS POST to:

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

Request Parameters

Every campaign mutate request requires the following two parameters:

Property

Type

Description

Required

operator

{ADD, REMOVE, SET, PAUSE, UNPAUSE}

Type of operation to perform (case sensitive). See the section below
for information regarding the PAUSE and UNPAUSE operations

Yes

operand

Campaign

The campaign to operate on

Yes

The properties of a Campaign request operand are:

Property

Type

Description

Required

Limits

name

String

Name of the campaign

If operator is ADD

100 chars

id

Long

ID of the campaign

If operator is SET, REMOVE, PAUSE or UNPAUSE (unless externalId is set)

10 digits

externalId

Long

External ID of the campaign

If operator is SET, REMOVE, PAUSE or UNPAUSE (unless id is set)

10 digits

servingStatus

String

Status of the campaign

No

9 chars

budget

Budget

Budget object for this request

No- See details below

11 digits total, 4 decimals

product

String

Type of the product of the campaign, default is PERFORMANCE

No

 
affiliateIdIntegerThe ID of the affiliate of the campaign. For SET if affiliateId is an empty string the current value will be removed.No4 digits
startDate

Datestring

Indicates when the campaign should start, In YYYYMMDD format. This date refers to the date that the creator of the campaign indicated that the campaign should start, not necessarily the date the campaign actually started. For the ADD and SET operations, this date cannot be before the current date. For the SET operation, this date cannot be before the creation date of the campaign.

No (default is current date)

 

endDate

Datestring

Indicates when the campaign should end, in YYYYMMDD format

No (default is to run indefinitely)

1000 chars

reason

String

The reason for the cancellation

If operator is REMOVE

 

statusReason

Integer

The ID of the status reason associated with campaign deactivation

No

 
Budget

The Campaign operand may or may not include a budget object. If you wish to set budget at the AdGroup level do not include the budget object in your Campaign API requests.  You may create a campaign budget at the time the campaign is created (ADD operation) or you may add it later using the campaign SET operation.  Once the budget is added at the Campaign level, it cannot be configured at the AdGroup level and vice versa. properties of a budget object in a request are as follows:

Property

Type

Description

Required

Notes

amount

Double

Amount of budget in U.S. Dollars

Yes

 

period

{Daily, Monthly}

Period over which to spend the budget

No

If this property is not supplied, the budget period defaults to monthly

Notes
Icon

A campaign will not become active until budget is added either at the Campaign level or the AdGroup level (the AdGroup API is used to configure budget at the AdGroup level).

Icon

Once an external ID is used to create campaign, that external ID cannot be reassigned to another campaign.

Icon

The campaignId and externalId properties cannot be submitted together for a mutate operation.

Icon

The period can not switched from monthly to daily or from daily to monthly once it is set.

Request Headers

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

Yes

Valid token

developerToken

The token received during registration

Yes

Valid token

 

Request Examples

Example 1: Create a campaign with a $3000 budget ending on 2017-05-20
Example 2: Update campaigns 3168332 and remove campaign 3981
Example 3: Update campaign 3168332, remove campaign 3981 (XML)

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

campaigns

Campaign list

List of campaigns

id

Long

The Campaign ID

externalId

Long

External ID of the campaign

name

String

The Campaign name

servingStatus

{ACTIVE, CANCELLED, PENDING,
SUSPENDED}

Status of the campaign

startDate

Datestring

Date that the creator of the campaign indicated the campaign should begin, YYYYMMDD format

endDate

Datestring

Date when the campaign ends, if any, YYYYMMDD format

cancelDate
Datestring

cancelDate will be set to following day in YYYYMMDD format when REMOVE operation is called.

Remain empty otherwise.

budgetAmount

Double

Current budget amount in U.S. Dollars

period

{DAILY, MONTHLY}

Period over which to spend the budget

affiliateIdIntegerThe affiliate ID of the campaign

Response Examples

Example 1: An XML success response
Example 2: A JSON success response to an ADD request
Example 3: A JSON success response to a SET request
Example 4: A JSON success response to a REMOVE request
Example 5: A JSON response for a duplicate ADD request
Example 6: A JSON response for a date change request on an active campaign
Example 7: A JSON response for a request to move the end date before the start date

PAUSE and UNPAUSE Operations

The PAUSE and UNPAUSE operations allow a user to pause Ad/Budget distribution for all AdGroups within a campaign and subsequently reactivate (unpause) the Ads/Budget at a later time.  When the PAUSE or UNPAUSE operations are indicated all other request parameters will be ignored as the only function of these operations is to change the campaign's servingStatus between ACTIVE and PAUSED.  Note that the user can only PAUSE an ACTIVE campaign (i.e. cannot pause campaigns that are PENDING, CANCELED, etc) and can only UNPAUSE a PAUSED campaign.

Icon

Note that when a campaign is set to PAUSE or UNPAUSE, the status will take affect immediately.

 

Example 8: A JSON PAUSE Request
Example PAUSE Operation
Example 9: A JSON PAUSE Response

 

Example 9: A JSON UNPAUSE Request
Example 10: A JSON UNPAUSE Response
  • No labels