> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Category Search

> Search for categories based on the category ID or retailer ID

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

## **Overview**

Product categories allow retailers to create a hierarchal structure that helps narrow down products into unique groups or sub-groups based on shared characteristics

Products can be associated with 0 to 3 levels of categories

**Category Hierarchy Example**

<table>
  <thead>
    <tr>
      <th>
        <p>
          CategoryId
        </p>
      </th>

      <th>
        <p>
          Category Text
        </p>
      </th>

      <th>
        <p>
          Category Name
        </p>
      </th>

      <th>
        <p>
          ParentId
        </p>
      </th>

      <th>
        <p>
          Level
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            100
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            pets
          </code>
        </p>
      </td>

      <td>
        <p>
          pets
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          Level 1
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            200
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            pets \\| dog supplies \\|
          </code>
        </p>
      </td>

      <td>
        <p>
          dog supplies
        </p>
      </td>

      <td>
        <p>
          100
        </p>
      </td>

      <td>
        <p>
          Level 2
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            300
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            pets \\| dog supplies \\| dog food & treats
          </code>
        </p>
      </td>

      <td>
        <p>
          dog food & treats
        </p>
      </td>

      <td>
        <p>
          200
        </p>
      </td>

      <td>
        <p>
          Level 3
        </p>
      </td>
    </tr>
  </tbody>
</table>

Retailer's categories can be narrowed by searching across category text (i.e searching for "dog" in the above example will show categories `200` and `300`)

An additional endpoint is provided to lookup categories by `categoryId` across all retailers in case looking up for a category by its unique ID is required

## **Endpoints**

<table>
  <thead>
    <tr>
      <th>
        <p>
          Verb
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            GET
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /categories/\{categoryId}
          </code>
        </p>
      </td>

      <td>
        <p>
          Search for categories based on category ID
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            GET
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /categories?retailerId=\{retailerId}&?textSubstring=\{textSubstring}
          </code>
        </p>
      </td>

      <td>
        <p>
          Search for retailer categories and filter down by a specific category name
        </p>
      </td>
    </tr>
  </tbody>
</table>

 

## **Category Query Parameters**

<ParamField path="retailerId" type="integer">
  *Optional.*

  **Default:** -

  **Is Nullable?** No

  The retailer id for which Categories fetched

  **Values:** int32
</ParamField>

<ParamField path="textSubstring" type="string">
  *Optional.*

  **Default:** -

  **Is Nullable?** No

  Query string to search for across category Text.

  **Values:** 500 char limit
</ParamField>

<ParamField path="pageIndex" type="integer">
  *Optional.*

  **Default:** `0`

  **Is Nullable?** No

  The number of Categories to skip before returning results. Maximum value is tentatively capped at 500 since we anticipate performance issues for particularly broad searches

  **Values:** int32
</ParamField>

<ParamField path="pageSize" type="integer">
  *Optional.*

  **Default:** `100`

  **Is Nullable?** No

  The max number of Categories to return. Max value capped at 100

  **Values:** int32
</ParamField>

 

## **Category Attributes**

<ParamField path="id" type="string">
  Unique ID of the category

  **Values:** 500 char limit
</ParamField>

<ParamField path="text" type="string">
  Full Category hierarchy name divided by a pipe `|` from the top level of the hierarchy down to the Category name. The value of text gets generated by attaching Category name recursively to it’s parent category using `|` symbol until there is no more parents

  **Values:** 500 char limit
</ParamField>

<ParamField path="name" type="string">
  Name of the category without hierarchy

  **Values:** 500 char limit
</ParamField>

<ParamField path="parentId" type="string">
  Id of the previous level in Category hierarchy.

  * **note:** if this is a level 1 category then ParentId is `"null"`

  **Values:** 500 char limit
</ParamField>

 

## **Get Category By Category ID**

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/categories/{categoryId}
  ```
</EndpointBadge>

**Sample Request**

```bash theme={null}
curl -L -X GET 'https://api.criteo.com/{version}/retail-media/line-items/330712460069138432' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
```

**Sample Response**

```json theme={null}
{
    "text": "clothing shoes & accessories",
    "name": "clothing shoes & accessories",
    "parentId": "0",
    "id": "3587794"
}
```

## **Get Categories by Retailer**

Results are paginated using `pageIndex` and `pageSize` query parameters; if omitted, defaults to `0` and `25`, respectively. See [API Response](/retail-media/docs/api-response#pagination).

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/categories
  ```
</EndpointBadge>

**Sample Request 1**\
*Searching by specifying one category name in the query parameters*

```bash theme={null}
curl -L -X GET 'https://api.criteo.com/{version}/retail-media/categories?retailerId=299&textSubstring=shoes' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
```

**Sample Response**

```json expandable theme={null}
{
    "data": [
        {
            "attributes": {
                "text": "shoes",
                "name": "shoes",
                "parentId": "0",
                "id": "3841975"
            },
            "id": "3841975",
            "type": "RetailMediaCategories"
        },
        {
            "attributes": {
                "text": "clothing shoes & accessories",
                "name": "clothing shoes & accessories",
                "parentId": "0",
                "id": "3587794"
            },
            "id": "3587794",
            "type": "RetailMediaCategories"
        },
        {
            "attributes": {
                "text": "men's clothing shoes & accessories",
                "name": "men's clothing shoes & accessories",
                "parentId": "0",
                "id": "3591642"
            },
            "id": "3591642",
            "type": "RetailMediaCategories"
        }
    ],
    "warnings": [],
    "errors": []
}
```

**Sample Request 2**\
*Searching by multiple categories' names within the same call*

```bash theme={null}
curl -L -X GET 'https://api.criteo.com/{version}/retail-media/categories?retailerId=299&textSubstring=sport,shoe,women' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
```

**Sample Response 2**

```json theme={null}
{
    "data": [
        {
            "attributes": {
                "text": "women's clothing shoes & accessories|men's accessories|sport & fitness",
                "name": "sport & fitness",
                "parentId": "3995507",
                "id": "4152273"
            },
            "id": "4152273",
            "type": "RetailMediaCategories"
        }
    ],
    "warnings": [],
    "errors": []
}
```

## **Responses**

<table>
  <thead>
    <tr>
      <th>
        <p>
          Response
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          🔵
        </p>

        <p>
          <code>
            200
          </code>
        </p>
      </td>

      <td>
        <p>
          Success
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴
        </p>

        <p>
          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          No IDs were passed in
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴
        </p>

        <p>
          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          A non-request input-based error occurred in the server.
        </p>
      </td>
    </tr>
  </tbody>
</table>