Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid AdGroup Geo API is part of the Advertising API suite and allows users to add and remove geographic targeting to ad groups.

AdGroup Geography types are PRIMARY , SECONDARY, and CUSTOMER_SELECTED_GEOGRAPHY. 

PRIMARY and SECONDARY are determined based on the listing address and will not be able to modified by AdGroup Geo API.

The CityGrid AdGroup Geo API is used only to add / remove CUSTOMER_SELECTED_GEOGRAPHY. 

Icon

The AdGroupGeo API must be called to associate geography data with an ad group when the ad group's business does not have a physical location (i.e. when the related place has isVirtual=true). It does not need to be called when the business does possess a physical address, since geographic targeting is initially inferred from the business address.

Contents

AdGroupGeo Get Endpoint

The adgroupgeo/get endpoint retrieves information about adgroup-geography associations. The operation is invoked via HTTPS GET to:

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

Request Parameters

Parameter

Description

Required

Type

Default

Example

adGroupId

The ad group whose associated geographies are to be retrieved

Yes

Long

N/A

 

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 received during registration

Yes

Valid token

 

Request Examples

Example 1: Retrieve adgroup-geography associations for ad group 38
Example 2: Get the third page of results for ad group 38, three results per page, in XML

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Total number of results

adGroupGeos

AdGroupGeo list

List of results

adGroupGeo

AdGroupGeo

An adgroup-geography association

adGroupId

Long

The ID of the ad group

adgroupGeoType

{PRIMARY, SECONDARY, CUSTOMER_SELECTED_GEOGRAPHY}

The type of association

geographyId

Long

The ID of the geography

geographyName

String

The name of the geography

geographyType

String

The type of the geography

Response Examples

Example 1: A JSON success response
Example 2: An XML success response
Example 3: No authentication token (JSON)
Example 4: Missing required parameter (XML)

AdGroupGeo Mutate Endpoint

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

These operations are invoked via HTTPS POST to:

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

Request Parameters

Every adgroupgeo/mutate request requires the following two parameters:

Property

Type

Description

Required

operator

{ADD, REMOVE}

Type of operation to perform (case sensitive)

Yes

operand

AdGroupGeo(s)

The association(s) to operate on

Yes

The properties of an adgroupgeo object in a request are:

Field

Description

Required

Type

adGroupId

ID of the ad group

Yes

Long

postalCodeTargetContains postal code geography dataNoPostalCodeTarget

cityTarget

Contains city geography data

No

CityTarget

metroTarget

Contains metro Geography data

No

MetroTarget

provinceTarget

Contains province Geography data

No

ProvinceTarget

neighborhood

Contains neighborhood Geography data

No

Neighborhood

Icon

You may specify one and only one geography type (postalCodeTarget, cityTarget, metroTarget, provinceTarget, or neighborhood).

The properties of a cityTarget are:

Field

Description

Required

Type

Limit

cityName

Name of the city

Yes

String

128 chars

provinceName

State/Province of the city

Yes

String

40 chars

The properties of a postalCodeTarget are:

Field

Description

Required

Type

Limit

postalCode

5 digit US postal code

Yes

String

5 digits

The properties of a metroTarget are:

Field

Description

Required

Type

Limit

metroName

Name of the metro

Yes, if metro code is not defined

String

60 chars

provinceName

Province or state abbreviation. Example: New York state abbreviation is NY.

Yes

String

40 chars

The properties of a provinceTarget are:

Field

Description

Required

Type

Limit

provinceName

Province or state abbreviation. Example: New York state abbreviation is NY.

Yes, if the province code is not defined

String

40 chars

The properties of a neighborhood are:

Field

Description

Required

Type

Limit

neighborhoodName

Name of the neighborhood

Yes

String

80 chars

provinceName

Province or state abbreviation. Example: New York state abbreviation is NY.

Yes

String

40 chars

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 Hudson, NY to ad group 78
Example 2: Remove Hudson, NY from ad group 78
Example 3: Add Postal Code 90048 to ad group 78
Example 4: Remove Postal Code 90048 from ad group 78
Example 5: Add Vinings, GA to ad group 1055
Example 6: Remove Vinings, GA from ad group 1055
Example 7: Add Sulphur Springs, TX Metro to ad group 1207
Example 8: Remove neighborhood East Highland Village, CA from ad group 1001
Example 9: Add California to ad group 78

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

adGroupId

Long

The ID of the ad group

geographyId

Long

The ID of the geography

geographyName

String

The name of the geography

geographyType

String

The type of the geography

Response Examples

All success responses are the same for ADD and REMOVE operations.

Example 1: JSON response for modified city target
Example 2: XML response for modified city target
Example 3: JSON response for modified postal code target
Example 4: XML response for modified city target
Example 5: JSON response for modified metro target
Example 6: XML response for modified metro target
Example 7: JSON response for modified neighborhood target
Example 8: XML response for modified neighborhood target
Example 9: JSON response for modified province target
Example 10: XML response for modified province target
Example 11: Incorrectly formatted ad group ID
  • No labels