Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid Category API allows applications to search for CityGrid categories, also known as criteria. It is part of the Advertising API suite and is intended for developers who are building applications for managing campaigns within the CityGrid network.

Icon

The terms category and criterion are used interchangeably in the Advertising APIs. The categoryId returned here should be passed as the adGroupCriterionId to the AdGroupCriterion API.

Contents

Category Lookup Endpoint

The category/get endpoint finds a list of categories (criteria) by keyword or by place. The operation is invoked via HTTPS GET to:

api.citygrid.com/content/category/v2/get

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

Request Parameters

Parameter

Description

Required

Type

Example

keywords

Text containing keywords

Only if placeId and externalPlaceId are absent

String

hotel restaurant

placeId

Place ID

Only if keywords and externalPlaceId are absent

Long

34454

externalPlaceId

External Place ID

Only if keywords and placeId are absent

String

1000499

startIndex

Page number of results to return (zero-based)

No

Integer

0

numberResults

Number of results per page

No

Integer

10

Conflicting parameters are handled as follows:

Parameter Scenario

Action

placeId and keywords are both given

keywords will be ignored

externalPlaceId and keywords are both given

keywords will be ignored

placeId and externalPlaceId are both given

Error: PARAMETER_ONLY_ONE

None of keywords, placeId and externalPlaceId are given

Error: PARAMETER_REQUIRED

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 up to three categories associated with the keyword "veterinary"
Example 2: Request the second page of categories for place 3680332, four categories per page
Example 3: Request up to the default number of categories for the place with external id abc123, in XML

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Total number of categories found

categories

Category list

The categories returned

categoryId

Long

ID of a category

categoryName

String

Name of a category

categoryType

{Primary, Secondary, Tertiary}

Type of a category (Primary, Secondary)

isPrimaryEligible

{true, false}

Whether this category is allowed as a primary category

categoryTree

Category list

List of subcategories

Icon

The category lookup endpoint returns different properties depending on the request. A request by keywords returns a nested tree of categories; a request by placeId returns a flat list of suggested categories as well as the categoryType field.

Response Examples

Example 1: A JSON response to a request for five categories associated with the keyword "veterinary"
Example 2: A JSON response to a request for five categories associated with the place 3680332
Example 3: A JSON response to a request without keywords, place id, or external place id
Example 4: An XML response to a request for five categories associated with the keyword "veterinary"
Example 5: An XML response to a request for five categories associated with the place 3680332
Example 6: An XML response to a request with a non-numeric place id
  • No labels