Ricardo Categories API Documentation Retrieve the Ricardo.ch category tree as a flat list: category id, name, tree level (1 is top level), leaf flag and parent id. Filter by parent category or level. Use the ids with the search and category endpoints. The tree changes rarely and is cached for 24 hours.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
3 optional filters available.
string
Optional
Return only the direct children of this category number, e.g. 41950. Omit to return the full tree as a flat list.
1234567890
integer
Optional
Return only categories of this tree level, 1 (top level) to 6.
10
string
Optional
Language of labels and the listing url: de or fr. Defaults to de.
en
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"total": 28,
"categories": [
{
"name": "Antiquit\u00e4ten & Kunst",
"level": 1,
"is_leaf": false,
"category_id": "38399"
},
{
"name": "Briefmarken",
"level": 1,
"is_leaf": false,
"category_id": "38766"
},
{
"name": "B\u00fccher & Comics",
"level": 1,
"is_leaf": false,
"category_id": "38889"
}
]
},
"meta": {
"billable": true,
"endpoint_family": "categories"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The parent_id is not a category number, or the level or language is out of range. This response is not billable.
{
"errors": {
"level": [
"The level must be between 1 and 6."
]
},
"message": "The request validation failed"
}Resource Not Found
The parent_id does not exist in the category tree. This response is not billable.
{
"error": {
"code": "NOT_FOUND",
"message": "The requested Ricardo resource was not found."
},
"success": false
}Invalid Source Response
Ricardo answered with a response Scrappa could not read. This response is not billable.
{
"error": {
"code": "PARSER_DRIFT",
"message": "Ricardo returned a response Scrappa could not read. Please retry later."
},
"success": false
}Service Unavailable
The upstream service is temporarily unavailable. Please retry shortly.
{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Ricardo API is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.