Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid AdGroup API is part of the Advertising API suite and enables developers to manage ad groups within a campaign. An ad group contains a collection of ads for a particular place, together with category and geographical targeting information. The API allows you to get and set data about the group. To manipulate the ads and targeting information within an ad group, see the AdGroupAd API, the AdGroupCriterion API, and the AdGroupGeo API.

The AdGroup API provides two endpoints: adgroup/get and adgroup/mutate.

Contents

AdGroup Get Endpoint

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

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

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

Request Parameters

Parameter

Description

Required

Type

Default

Example

adGroupIds

Specified to retrieve ad groups by ID

Only if campaignId and placeId are both missing

Long list (Comma-delimited)

N/A

4556,45,3344

externalPlaceId

Specified to retrieve ad groups by place using the place's external ID

No

String

N/A

compexu3821

placeId

Specified to retrieve ad groups by place

Only if campaignId and adGroupIds are both missing

Long

N/A

442442

campaignId

Specified to retrieve ad groups in a campaign

Only if placeId and adGroupIds are both missing

Long

N/A

144534

startIndex

Page number of results to return (zero-based)

No

Integer

0

5

numberResults

Number of results per page

No

Integer

10

25

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 you received at registration

Yes

Valid Token

Request Examples

Example 1: Request up to 3 ad groups for campaign 16631
Example 2: Request ad groups 6, 11, and 155 in XML
Example 3: Request the default number of ad groups for external place aa-123

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Number of ad groups returned

adGroups

AdGroup list

Container for multiple ad groups

adGroup

AdGroup

Details on a single ad group

id

Long

ID of the ad group

externalPlaceIdStringExternal ID of the place associated with the ad group

placeId

Long

ID of the place associated with the ad group

campaignId

Long

ID of the campaign that this ad group belongs to

businessPhone

String

Business ring-to number. This field is populated only when there is no metered phone line provisioned by CGM, but displayPhone and businessPhone information was previously supplied in the request.

providerPhone

String

The phone number that CGM provisioned a metered line for: either the existing metered line already provided by the advertising partner, or, if the advertising partner has not provisioned its own metered line, the business ring-to number. This field is populated only when a metered phone line is provisioned by CGM.

displayPhone

String

The displayPhone provided in the request or the metered line number if a line has been provisioned by CGM.

meteredPhoneType

{LOCAL, TOLLFREE}

Metered phone number type

recordCalls

{true, false}

Whether calls may be recorded.

meteredLineStatus

{0, 1, 2}

Status of the metered line: 0 = no or inactive metered line, 1 = has metered line, 2 = pending

name <deprecated>

String

Arbitrary name of the ad group

status

{Active, Inactive, Pending, Cancelled, Paused}

Status

bids

Bid list

List of bids

ppe

Double

PPE (Price per Event) of the action of the bid

actionTargetName

String

Action of the bid

email

String

Business email

Response Examples

Example 1: A JSON success response
Example 2: An XML success response
Example 3: A response to a missing (misspelled) required parameter

A request with the parameter adGroupIds misspelled as ids will produce a result such as:

Example 4: A response to a non-numeric ad group id

A request to api.citygrid.com/advertising/adgroup/v2/get?adGroupIds=234,4A produces a response such as:

AdGroup Mutate Endpoint

The adgroup/mutateendpoint uses five operators to provide the following operations:

  • The ADD operator creates an ad group.
  • The SET operator updates ad group properties.
  • The PAUSE operator pauses an ad group
  • The UNPAUSE operator re-activates a paused ad group
  • The REMOVE operator cancels an ad group.
Icon

Please note that when the operation is REMOVE, the ad group is not physically removed from the system.

These operations are invoked via HTTPS POST to:

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

Request Parameters

Every adgroup/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

Ad Group

The ad group to operate on

Yes

The properties of an ad group object in a request are:

Property

Description

Type

Required

Limit

adGroupId

The ID of the ad group

Long

If operator is SET or REMOVE

10 digits

externalPlaceId

External ID of the place

String

If operator is ADD

256 chars

placeId

ID of the Place

Long

If operator is ADD

10 digits

campaignId

ID of the campaign containing the ad group

Long

If operator is ADD

10 digits

contractTermMonths

The duration in months of the contract

Integer

No. 0 es a valid value for SET operator

 

monthlyServiceFee

The monthly fee associated with the ad group

Double

No. 0 is a valid value for SET operator

 

bids

Bid list

Bid

If operator is ADD

see below

budget

Budget object for this request

Budget

No- See details below

see below
businessPhone

The number to be displayed on place pages in the CityGrid network

String

No

see below

displayPhone

The number to be displayed on place pages in the CityGrid network

String

No

see below

meteredPhoneType

Metered phone number type

{LOCAL, TOLLFREE}

No

 

recordCalls

Whether call recording is set on the metered line

{0, 1}

No

 

email

The primary email for this business

String

No

60 chars

assignMeteredLine

How a metered line is provisioned. 0=Provision a metered line. 1=Do NOT provision a metered line.

{0, 1}

No. If not specified, a metered line will be provisioned (default = 0).

 

Bids

The properties of a bid object in an ad group in a request are:

Property

Description

Required

Type

Default

Example

Limit

ppe

The PPE (Price per Event) of the action of the bid

Yes

Double

N/A

1.30

7 digits for integer part, 4 decimals

actionTargetName

The action of the bid

Yes

String

N/A

listing_profile

40 chars

Advertisers should set up a bid amount for each of the following action targets:

  • consumer reviews views
  • customer website link
  • enhanced merchant profile
  • get directions
  • map & directions
  • partner menu link
  • partner reservation link
  • print map
  • print offer
  • print profile
  • send to friend (email)
  • send to phone (press send)
  • trackable phone number

For virtual places, the only available action target is:

  • customer website link
Budget

The AdGroup operand may or may not include a budget object.  If you wish to set budget at the Campaign level do not include the budget object in your AdGroup API requests.  You may create an AdGroup budget at the time the AdGroup is created (ADD operation) or you may add it later using the AdGroup SET operation.  Once the budget is added at the AdGroup level, it cannot be configured at the Campaign level and vice versa. The 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

Max 7 digits for integer part, 4 decimals

period

Daily/
Monthly

Period over which to spend the budget

No

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

Notes:

  • 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).
  • Entering an empty string into the businessPhone and displayPhone will remove the values from the ad group.
  • After removing businessPhone and displayPhone, the GET operation will return an empty string for meteredPhoneType and recordCalls, and 0 for meteredLineStatus. Furthermore, updates to meteredPhoneType and recordCalls will not be allowed unless businessPhone and displayPhone are added or are nonempty in the same request.
  • Removing only one of businessPhone or displayPhone field will produce an error with response code PARAMETER_ASSOCIATION_ACTION_NOT_PERFORMED.
  • If no businessPhone is present, the phone number associated with the place will be used as the business phone.
  • A budget provider customer can provision a line by specifying 0 in the assignMeteredLine field
  • Entering an empty string into the email field will remove the value from the ad group.
  • The following fields are considered non-removable, in that entering an empty string to any of these fields will produce an error with response code PARAMETER_INVALID:
    • contractTermMonths
    • monthlyServiceFee
    • meteredPhoneType
    • recordCalls
    • assignMeteredLine
  • Entering an empty string into the bids field will produce an error with response code INVALID_REQUEST_BODY.
  • The following phone format are accepted:
    • (312)456-7890

    • 3214567890

    • 312-456-7890

    • +1 (215)456-7890

  • Entering an empty string into the ppe field will produce an error with response code PARAMETER_INVALID.
  • Entering an empty string into the budget.amount or budget.period results in a PARAMETER_INVALID error.
  • If the ad group's place is virtual, then adding or setting any of the following fields will produce an error with response code PARAMETER_NOT_SUPPORTED:
    • businessPhone
    • displayPhone
    • meteredPhoneType
    • recordCalls
    • assignMeteredLine
  • When performing a SET operation:
    • If no phone information is passed in the request, the line associated to the ad group (if any) remains untouched.
    • If phone information is passed in the request, then:
      • For an ad group with no metered line associated: A new metered line is associated using the input parameters. The line is provisioned depending on the input parameters.
      • For an ad group with a line that has not been provisioned: The line is updated using both the input parameters and the data from the current line. If the businessPhone is not passed in, then the current ring-to number is used for the business phone. If the displayPhone is not passed in, then the current provisioned number used for the display phone.
      • For an ad group with a previously provisioned line:
        • If the current request is to not provision a line, then the current line is deleted, and a new line is associated to the ad group using the phone information from the request.
        • If the current request is to provision a line, then the current line is updated using the phone information from the request and the information from the current line. If the businessPhone parameter is not passed in, the place's phone number is used for the business phone. If the displayPhone parameter is not passed in, the current ring-to number is used for the display phone.

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 you received at registration

Yes

Valid Token

Request Examples

Example 1: Create a new ad group
Example 2: Update an ad group

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Number of ad groups affected by mutate

adGroups

AdGroup list

ad group(s) affected by the mutate

id

Long

The id of the ad group

placeId

Long

The ID of the place this ad group is assigned to

externalPlaceId

String

External ID of the place this ad group is assigned to

campaignId

Long

The ID of the campaign this ad group is part of

productId

Long

The ID of the product associated to the ad group

contractTermMonths

Integer

The duration in months of the contract

monthlyServiceFee

Double

The monthly fee associated to the ad group in U.S. Dollars

name

String

The name of the ad group (currently blank)

status

{Active, Inactive, Pending, Cancelled, Paused}

The status of the ad group

displayPhone

String

same as request

businessPhone

String

same as request

providerPhone

String

The phone number that CGM provisioned a metered line for: either the existing metered line already provided by the advertising partner, or, if the advertising partner has not provisioned its own metered line, the business ring-to number. This field is populated only when a metered phone line is provisioned by CGM.

recordCalls

{0, 1}

same as request

assignMeteredLine

{0, 1}

same as request

meteredLineType

{LOCAL, TOLLFREE}

Metered line type, same as request

meteredLineStatus

{0, 1, 2}

metered line status 0=Inactive, 1=active, 2=pending

email

String

Business email

bids

Bid list

Bids applied to this ad group

ppe

Double

The PPE (Price per Event) of the action of the bid

actionTargetName

String

The action of the bid

Response Examples

Example 1: A JSON success response
Example 2: An XML success response
Example 3: An XML error response (change request still pending)
Example 4: A JSON error response (change request still pending)
Example 6: A JSON error response after trying to remove only the displayPhone field

PAUSE and UNPAUSE Operations

The PAUSE and UNPAUSE operations allow a user to pause Ad/Budget distribution for a specific AdGroup 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 ad group (i.e. cannot pause campaigns that are PENDING, CANCELED, etc) and can only UNPAUSE a PAUSED ad group.

Icon

Note that when an ad group is set to PAUSE or UNPAUSE, the status will take affect immediately.

 

Example 7: A JSON PAUSE Request
Example 8: A JSON PAUSE response
Example 9: A JSON UNPAUSE Request
Example 10: A JSON UNPAUSE Response
  • No labels