Description
This method replaces the legacy.retrieve_segment method.
This method returns all the categories created for your account. Using the input parameters, you can control how many fields to return in the response message, and the offiset to skip in the numerical order. This latter input parameter is useful when you are building a user interface displaying all your categories that includes paging. Rather than pull the complete set of categories, you only pull the ones you need depending upon which page the user is viewing in the interface.
The collection of categories is encapsulated within the <categories> element. The details of each category are in turn, encapsulated within the <item> element. Hence:
<categories>
<item>
… category elements
</item>
<item>
… category elements
</item>
… additional categories
</categories>
The list of categories will be sorted by category ID in ascending order.
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| limit | A numeric value specifying how many static segment records will be included in the response message. | string | No | 25 |
| offset | A numeric value specifying how many static segment records to skip from the response. Use this element when you are using this API to construct a user interface that displays the complete list of static segments over several "pages". | string | No | 26 |
Response
| Field | Description | Example |
|---|---|---|
| responseCode | A code indicating either success or failure of the operation. (see Error Codes below) | 180 |
| responseText | Human readable description of the response code | Displaying all categories |
| category_id | The category ID number. | 255475 |
| category_name | The category name. | Music Preference |
Response Codes
| Error Condition | responseCode | responseText |
|---|---|---|
| Successful operation; all categories in the system are returned with no offset or limit. | 180 | Displaying all categories |
| There are fewer categories in the system than specified by the <offset> value. | 181 | Offset exceeds number of categories |
| There are no categories in the system to return | 182 | No categoris returned |
| Successful operation; the subset of categories defined by the limit and offset are returned. | 183 | Retrieved subset of categories |
Example Post
<methodCall>
<methodName>account.getCategories</methodName>
<limit>2</limit>
<offset>5</offset>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>account.getCategories</methodName>
<responseCode>183</responseCode>
<responseText>Retrieved subset of categories</responseText>
<responseData>
<categories>
<item>
<category_name>Music Genres</category_name>
<category_id>3415</category_id>
</item>
<item>
<category_name>Sports</category_name>
<category_id>3753</category_id>
</item>
</categories>
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>
Example Error
<methodResponse>
<item>
<methodName>account.getCategories</methodName>
<responseCode>181</responseCode>
<responseText>Offset exceeds number of categories</responseText>
<responseData></responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>