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	100	Level 2
`300`	`pets \\| dog supplies \\| dog food & treats`	dog food & treats	200	Level 3

CategoryId

Category Text

Category Name

ParentId

Level

100

pets

pets

Level 1

200

pets \| dog supplies \|

dog supplies

100

Level 2

300

pets \| dog supplies \| dog food & treats

dog food & treats

200

Level 3

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

integer

Optional.Default: -Is Nullable? NoThe retailer id for which Categories fetchedValues: int32

textSubstring

string

Optional.Default: -Is Nullable? NoQuery string to search for across category Text.Values: 500 char limit

pageIndex

integer

Optional.Default: 0Is Nullable? NoThe number of Categories to skip before returning results. Maximum value is tentatively capped at 500 since we anticipate performance issues for particularly broad searchesValues: int32

pageSize

integer

Optional.Default: 100Is Nullable? NoThe max number of Categories to return. Max value capped at 100Values: int32

Category Attributes

string

Unique ID of the categoryValues: 500 char limit

text

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 parentsValues: 500 char limit

name

string

Name of the category without hierarchyValues: 500 char limit

parentId

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

Get Category By Category ID

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. 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.

Introduction

Guides for Retail Media API

Overview

Endpoints

Category Query Parameters

Category Attributes

Get Category By Category ID

Get Categories by Retailer

Responses

​Overview

​Endpoints

​Category Query Parameters

​Category Attributes

​Get Category By Category ID

​Get Categories by Retailer

​Responses

Overview

Endpoints

Category Query Parameters

Category Attributes

Get Category By Category ID

Get Categories by Retailer

Responses