Category Search

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

CategoryId	Category Text	Category Name	ParentId	Level
`100`	`pets`	pets	-	Level 1
`200`	`pets \	dog supplies \	`	dog supplies
`300`	`pets \	dog supplies \	dog food & treats`	dog food & treats

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

Verb	Endpoint	Description
`GET`	`/categories/{categoryId}`	Search for categories based on category ID
`GET`	`/categories?retailerId={retailerId}&?textSubstring={textSubstring}`	Search for retailer categories and filter down by a specific category name

Category Query Parameters

retailerId Optional

Data Type: integer
Values: int32
Default: -
Nullable? No

Description: The retailer id for which Categories fetched

textSubstring Optional

Data Type: string
Values: 500 char limit
Default: -
Nullable? No

Description: Query string to search for across category Text.

pageIndex Optional

Data Type: integer
Values: int32
Default: 0
Nullable? No

Description: 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

pageSize Optional

Data Type: integer
Values: int32
Default: 100
Nullable? No

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

Category Attributes

Data Type: string
Values: 500 char limit

Description: Unique ID of the category

text

Data Type: string
Values: 500 char limit

Description: 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

name

Data Type: string
Values: 500 char limit

Description: Name of the category without hierarchy

parentId

Data Type: string
Values: 500 char limit

Description: Id of the previous level in Category hierarchy.

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

Get Category By Category ID

https://api.criteo.com/{version}/retail-media/categories/{categoryId}

Sample Request

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

{
    "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

https://api.criteo.com/{version}/retail-media/categories?retailerId={retailerId}&?textSubstring={textSubstring}&pageIndex={pageIndex}&pageSize={pageSize}

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

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

Sample Response

{
    "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

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

{
    "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

Response	Description
🔵 `200`	Success
🔴 `400`	No IDs were passed in
🔴 `400`	A non-request input-based error occurred in the server.

Response

Description

🔵

200

Success

🔴

400

No IDs were passed in

🔴

400

A non-request input-based error occurred in the server.