Search Published Categories

get

/content/published/api/v1.1/taxonomies/{id}/categories

Use this query to search published categories. You can control the number of categories to be fetched, paginated, and sorted. Additionally, this resource can fetch field values of matching items.
Query expression syntax supports conditions that match the field values. Query conditions can be joined by using AND/OR operators and grouped with parenthesis. Below are general examples of queries.

Query expression ?q=(name co "car")
Query expression usage with this resource /published/api/v1.1/taxonomies/{id}/categories?q=(name co "car")


In general one form of filtering is supported by this resource.
  • Query all categories within a taxonomy: All categories of the taxonomy are queried. However, query conditions are limited to standard fields (id, name, parent.id) and/or optional fields (ancestors.id, ancestors.name, ancestors.apiName).
    For example: /published/api/v1.1/taxonomies/{id}/categories?q=(id eq "B0A39B47122C4CE88A6CD52B90C15263")





OperatorExampleSupported data typesDescription
eqq=(id eq "B0A39B47122C4CE88A6CD52B90C15263")

q=(name eq "Cars")

q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB")

q=(ancestors.id eq "C7117D407B1845DEAABBE00526D112FB")

q=(ancestors.name eq "car")

q=(ancestors.apiName eq "tax-c-c1")
textEquals operator (eq) matches the exact value supplied in the query. The value provided with this operator is not case-sensitive (name) except for identifier fields (id, parent.id, ancestors.id). This operator considers even special characters in the value.
coq=(name co "car red")

q=(ancestors.name co "car")

textContains operator (co) matches every word given in the criteria. It gives the results that have at least one of the words (in this example, car or red or both). This operator does not consider special characters in the value while searching.

This operator is applicable to text in case of single-valued attributes. The value provided with this operator is not case-sensitive.
swq=(name sw "Car")

q=(ancestors.name sw "ca")
textStarts With operator (sw) matches only the initial character values given in the field condition. The value provided with this operator is not case-sensitive.



Request Headers (Optional):
Header NameHeader Value
channelToken{valid channel token value}
Acceptapplication/json

Request

Path Parameters
Query Parameters
  • Channel token of the publish target. A channel token must be provided as either a query parameter or a request header.
  • The fields parameter is used to control the returned fields and values in the queried category. This parameter accepts a comma-separated list of field names or all. These fields will be returned for each queried category. As all the field names are case-sensitive, users must provide the correct field names in the search query. When fields is specified as all (case-insensitive), all the standard fields and optional fields are returned for each category. Each category has both standard fields (id, name, description, parent) and optional fields (ancestors, children). The standard field id is always returned in the response and cannot be filtered out. This parameter is optional in the query and by default query result shows only id, name and description in the response. Any incorrect or invalid field name given will result in an error.

    Example: ?q=(name co "car")&fields=name,description,parent,ancestors
    This returns id, name, description, parent and ancestors in the search results for a category containing "car" in the name field.
    Example: ?fields=name,parent
    This will return only standard fields (such as id, name and parent) for all categories within the default limit.
    Example: ?fields=name,children
    This will return only id, name and the children count for all categories within the default limit.
    Default Value: name,description
  • Number of rows to return.
    Default Value: 100
  • Start index of response rows.
    Default Value: 0
  • The orderBy parameter is used to control the order (ascending or descending) of queried items. This parameter is optional in the query and by default there is no order of results. This parameter accepts field names separated by a colon (:), which the user wants to sort the results and sort order.
    format: orderBy={fieldName}:{asc/des} (*Note: asc stands for ascending and des for descending. asc and des are always in lower case.)
    In a category query, fieldName can be name or position (standard field). When sorting results by position it is important to remember that only searches by parent.id can actually benefit from it. The category position is unique only within a given level or under a given parent category. There will be different categories with the same position value at different levels of the taxonomy. The sort order is optional and by default it is ascending. Any incorrect or invalid field name given will result in an error.

    Example: orderBy=name:asc
    Returns all categories in ascending order of name.

    Example: orderBy=name:des
    Returns all categories in descending order of name.

    Example: orderBy=position:asc
    Returns all categories in ascending order of position.

    Example: orderBy=position:des
    Returns all categories in descending order of position.
  • This parameter accepts a query expression condition that matches the field values. Many such query conditions can be joined using AND/OR operators and grouped with parentheses. The value of query condition follows the format of {fieldName} {operator} "{fieldValue}". The only values allowed in the operator are eq (Equals), co (Contains) and sw (Startswith).
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name eq "Furnitures")
    This will return all categories matching exactly the name "Furnitures".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name co "chairs" OR name co "red")
    This will return all categories containing the words "chairs" or "red".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(name sw "cars")
    This will return all categories which name start with "cars".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(apiName eq "cars-apiname")
    This will return all categories which apiName matches "cars-apiname".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(id eq "B0A39B47122C4CE88A6CD52B90C15263")
    This will return a category with the given identifier.
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.id eq "B0A39B47122C4CE88A6CD52B90C15263")
    This will return the categories with an ancestor with the given identifier.
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name eq "Furnitures")
    This will return all categories with an ancestor matching exactly the name "Furnitures".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name co "chairs" OR ancestors.name co "red")
    This will return all categories with an ancestor containing the words "chairs" or "red".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.name sw "cars")
    This will return all categories with an ancestor which name starts with "cars".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(ancestors.apiName eq "cars-apiname")
    This will return all categories which apiName matches "cars-apiname".
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB")&orderBy=position:asc
    This will return all children categories underneath the given parent identifier sorted by their position in ascending order.
    Example:
    https://{cecsdomain}/content/published/api/v1.1/taxonomies/{id}/categories?q=(parent.id eq "C7117D407B1845DEAABBE00526D112FB" AND name co "blue")
    This will return all children categories underneath the given parent identifier which contains the word "blue" in their names.
  • Accepts a Boolean value. Setting it to true displays the total results field in the response.
    Default Value: false
Back to Top

Response

Supported Media Types

200 Response

Successful operation.
Body ()
Root Schema : CollectionProperties
Type: object
CollectionProperties.
Show Source
Nested Schema : aggregationResults
Type: array
Aggregation results.
Show Source
Nested Schema : items
Type: array
Singular resources contained in the collection.
Show Source
Nested Schema : pinned
Type: array
Pinned items. Shows items pinned at the top of search list
Show Source
Nested Schema : properties
Type: object
Additional Properties Allowed
Show Source
additional collection properties.
Nested Schema : AggregationResult
Type: object
Show Source
Nested Schema : items
Type: object
Nested Schema : additionalProperties
Type: object

400 Response

Bad Request. The server is unable to process the request on the client side due to malformed syntax, invalid data or message framing.

403 Response

Forbidden. Client is not authorized to perform this request.

500 Response

Internal server error. An unexpected error condition encountered in the system.
Back to Top

Examples

The following example shows how to search published taxonomy categories.

curl -i -X GET -H "Accept:application/json" 'http://<hostname>/content/published/api/v1.1/taxonomies/{id}/categories'
Example 1

Searches published taxonomy category with taxonomy id: 26950D77A5654D8BA407AC9F7DBCFF1F, having category id: 2069018ECE874C2DAA4051E9C16AD244 with channelToken: 1a3885a5a75b40baafe6495eb0b1125b.

/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=%28+id+eq+%222069018ECE874C2DAA4051E9C16AD244%22%29&totalResults=true&offset=0&orderBy=name%3Aasc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all

Response Body

{
        ody": {
        "hasMore": false,
        "offset": 0,
        "count": 1,
        "limit": 1,
        "totalResults": 1,
        "items": [
          {
            "apiName": "t31-c-c-c1",
            "id": "2069018ECE874C2DAA4051E9C16AD244",
            "name": "car red medium",
            "description": "car red medium description",
            "position": 1,
            "parent": {
              "id": "50AE00A8234B4AE1B675D36989F8B9CF",
              "name": "car red",
              "apiName": "t31-c-c"
            },
            "ancestors": [
              {
                "id": "6775D3D56E184CC3B8EC59A32AF1DD73",
                "name": "car",
                "apiName": "t31-c"
              },
              {
                "id": "50AE00A8234B4AE1B675D36989F8B9CF",
                "name": "car red",
                "apiName": "t31-c-c"
              }
            ],
            "links": [
              {
                "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories/2069018ECE874C2DAA4051E9C16AD244?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
                "rel": "self",
                "method": "GET",
                "mediaType": "application/json"
              }
            ]
          }
        ],
        "links": [
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "self",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "canonical",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/metadata-catalog/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
            "rel": "describedby",
            "method": "GET",
            "mediaType": "application/schema+json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "first",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( id eq \"2069018ECE874C2DAA4051E9C16AD244\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "last",
            "method": "GET",
            "mediaType": "application/json"
          }
Example 2

This searches published taxonomy categories with taxonomy id: 26950D77A5654D8BA407AC9F7DBCFF1F, with category name equals to car blue with channelToken:1a3885a5a75b40baafe6495eb0b1125b

/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=%28+name+eq+%22car+blue%22%29&totalResults=true&offset=0&orderBy=name%3Aasc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all

Response Body

{
        "hasMore": false,
        "offset": 0,
        "count": 1,
        "limit": 1,
        "totalResults": 1,
        "items": [
          {
            "apiName": "t31-car-blue-26950d77a5654d8ba407ac9f7dbcff1f",
            "id": "5096C5762F9540BCB23AA13001CA872E",
            "name": "car blue",
            "description": "car description",
            "position": 1,
            "parent": {
              "id": "6775D3D56E184CC3B8EC59A32AF1DD73",
              "name": "car",
              "apiName": "t31-c"
            },
            "ancestors": [
              {
                "id": "6775D3D56E184CC3B8EC59A32AF1DD73",
                "name": "car",
                "apiName": "t31-c"
              }
            ],
            "links": [
              {
                "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories/5096C5762F9540BCB23AA13001CA872E?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
                "rel": "self",
                "method": "GET",
                "mediaType": "application/json"
              }
            ]
          }
        ],
        "links": [
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "self",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "canonical",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/metadata-catalog/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?channelToken=1a3885a5a75b40baafe6495eb0b1125b",
            "rel": "describedby",
            "method": "GET",
            "mediaType": "application/schema+json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "first",
            "method": "GET",
            "mediaType": "application/json"
          },
          {
            "href": "https://<hostname>/content/published/api/v1.1/taxonomies/26950D77A5654D8BA407AC9F7DBCFF1F/categories?q=( name eq \"car blue\")&totalResults=true&offset=0&orderBy=name:asc&channelToken=1a3885a5a75b40baafe6495eb0b1125b&fields=all",
            "rel": "last",
            "method": "GET",
            "mediaType": "application/json"
          }
        ]
      }
    }
  ]
Back to Top