Category API

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.

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.

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"

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/content/category/v2/get?keywords=veterinary&numberResults=3'

Example 2: Request the second page of categories for place 3680332, four categories per page

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/content/category/v2/get?placeId=3680332&startIndex=1&numberResults=4'

Example 3: Request up to the default number of categories for the place with external id abc123, in XML

curl -X GET \
    -H 'Accept:application/xml' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/content/category/v2/get?externalid=abc123'

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

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"

{
  "totalNumEntries": 5,
  "response": {
    "field": "",
    "message": "Success",
    "code": SUCCESS
  },
  "categories": [
    {
      "categoryId": 3634,
      "categoryName": "Veterinarians",
      "isPrimaryEligible": "true",
      "categoryTree": [
        {
          "categoryId": 3643,
          "categoryName": "Veterinary Surgeons",
          "isPrimaryEligible": "true"
        },
        {
          "categoryId": 3637,
          "categoryName": "Veterinary Dentists",
          "isPrimaryEligible": "true"
        },
        {
          "categoryId": 3638,
          "categoryName": "Veterinary Dermatologists",
          "isPrimaryEligible": "true"
        }
      ]
    },
    {
      "categoryId": 2020,
      "categoryName": "Insurance Agents & Brokers",
      "isPrimaryEligible": "true",
      "categoryTree": [
        {
          "categoryId": 2028,
          "categoryName": "Pet Insurance",
          "isPrimaryEligible": "true"
        }
      ]
    },
    {
      "categoryId": 3630,
      "categoryName": "Veterinary Services",
      "isPrimaryEligible": "true",
      "categoryTree": [
        {
          "categoryId": 3632,
          "categoryName": "Animal Hospitals",
          "isPrimaryEligible": "true"
        },
        {
          "categoryId": 3634,
          "categoryName": "Veterinarians",
          "isPrimaryEligible": "true"
        }
      ]
    },
    {
      "categoryId": 2643,
      "categoryName": "Medical Equipment Manufacturers",
      "isPrimaryEligible": "true",
      "categoryTree": [
        {
          "categoryId": 2660,
          "categoryName": "Veterinary Equipment Manufacturers",
          "isPrimaryEligible": "true"
        }
      ]
    },
    {
      "categoryId": 3581,
      "categoryName": "Pets & Animals",
      "isPrimaryEligible": "true",
      "categoryTree": [
        {
          "categoryId": 3630,
          "categoryName": "Veterinary Services",
          "isPrimaryEligible": "true"
        }
      ]
    }
  ]
}

Example 2: A JSON response to a request for five categories associated with the place 3680332

{
  "totalNumEntries": 13,
  "response": {
    "field": "",
    "message": "Success",
    "code": SUCCESS
  },
  "categories": [
    {
      "categoryId": 1722,
      "categoryName": "Restaurants",
      "categoryType": "Primary"
    },
    {
      "categoryId": 11284,
      "categoryName": "Local Favorite",
      "categoryType": "Secondary"
    },
    {
      "categoryId": 1724,
      "categoryName": "Barbecue Restaurants",
      "categoryType": "Secondary"
    },
    {
      "categoryId": 11339,
      "categoryName": "Cash",
      "categoryType": "Secondary"
    },
    {
      "categoryId": 11231,
      "categoryName": "$",
      "categoryType": "Secondary"
    }
  ]
}

Example 3: A JSON response to a request without keywords, place id, or external place id

{
  "totalNumEntries": 0,
  "response": {
    "field": "",
    "message": "One of keywords, placeId or externalPlaceId is required",
    "code": "PARAMETER_REQUIRED"
  },
  "categories": [
  ]
}

Example 4: An XML response to a request for five categories associated with the keyword "veterinary"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>5</totalNumEntries>
  <response>
    <field/>
    <message>Success</message>
    <code>SUCCESS</code>
  </response>  
  <categories>
    <category>
      <categoryId>3634</categoryId>
      <categoryName>Veterinarians</categoryName>
      <isPrimaryEligible>true</isPrimaryEligible>
      <categoryTree>
        <category>
          <categoryId>3643</categoryId>
          <categoryName>Veterinary Surgeons</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
        <category>
          <categoryId>3637</categoryId>
          <categoryName>Veterinary Dentists</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
        <category>
          <categoryId>3638</categoryId>
          <categoryName>Veterinary Dermatologists</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
      </categoryTree>
    </category>
    <category>
      <categoryId>2020</categoryId>
      <categoryName>Insurance Agents &amp; Brokers</categoryName>
      <isPrimaryEligible>true</isPrimaryEligible>
      <categoryTree>
        <category>
          <categoryId>2028</categoryId>
          <categoryName>Pet Insurance</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
      </categoryTree>
    </category>
    <category>
      <categoryId>3630</categoryId>
      <categoryName>Veterinary Services</categoryName>
      <isPrimaryEligible>true</isPrimaryEligible>
      <categoryTree>
        <category>
          <categoryId>3632</categoryId>
          <categoryName>Animal Hospitals</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
        <category>
          <categoryId>3634</categoryId>
          <categoryName>Veterinarians</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
      </categoryTree>
    </category>
    <category>
      <categoryId>2643</categoryId>
      <categoryName>Medical Equipment Manufacturers</categoryName>
      <isPrimaryEligible>true</isPrimaryEligible>
      <categoryTree>
        <category>
          <categoryId>2660</categoryId>
          <categoryName>Veterinary Equipment Manufacturers</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
      </categoryTree>
    </category>
    <category>
      <categoryId>3581</categoryId>
      <categoryName>Pets &amp; Animals</categoryName>
      <isPrimaryEligible>true</isPrimaryEligible>
      <categoryTree>
        <category>
          <categoryId>3630</categoryId>
          <categoryName>Veterinary Services</categoryName>
          <isPrimaryEligible>true</isPrimaryEligible>
        </category>
      </categoryTree>
    </category>
  </categories>
</results>

Example 5: An XML response to a request for five categories associated with the place 3680332

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>13</totalNumEntries>
  <response>
    <field/>
    <message>Success</message>
    <code>SUCCESS</code>
  </response>
  <categories>
    <category>
      <categoryId>1722</categoryId>
      <categoryName>Restaurants</categoryName>
      <categoryType>Primary</categoryType>
    </category>
    <category>
      <categoryId>11284</categoryId>
      <categoryName>Local Favorite</categoryName>
      <categoryType>Secondary</categoryType>
    </category>
    <category>
      <categoryId>1724</categoryId>
      <categoryName>Barbecue Restaurants</categoryName>
      <categoryType>Secondary</categoryType>
    </category>
    <category>
      <categoryId>11339</categoryId>
      <categoryName>Cash</categoryName>
      <categoryType>Secondary</categoryType>
    </category>
    <category>
      <categoryId>11231</categoryId>
      <categoryName>$</categoryName>
      <categoryType>Secondary</categoryType>
    </category>
  </categories>
</results>

Example 6: An XML response to a request with a non-numeric place id

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>0</totalNumEntries>
  <response>
    <field/>
    <message>The parameter placeId is formatted incorrectly.  Valid formats are number.</message>
    <code>PARAMETER_FORMAT</code>
  </response>
  <categories/>
</results>