Categories¶
The category tree contains all the information about category definitions, attribute definitions and validation rules for placing ads.
The category tree has the following properties:
categories form a tree with a single root node |
each category has a unique id |
each category specifies the locales for which it is available |
each ad belongs to one and only one category |
ads can only be placed in leaf categories |
only leaf categories contain attributes |
The full tree (or a subtree) can be fetched using GET /categories.
Category Ids¶
The root node has category id 0.
Every other category id is a unique integer value within the range [1..2^53).
Category Levels¶
Although the number of sub levels is not limited, the category tree has up to three levels of categories (L1-3). The root node is considered special and resides at Level 0 (L0). Performing a search at the root node would result in a site-wide search across all categories.
Category Status¶
Each category has a status of one of the following values:
Status |
Description |
|---|---|
ACTIVE |
The category is visible. |
CLOSED |
The category is visible but no ads can be placed. This status should be
used for leaf categories where no new ads are accepted and which are
in transition to |
DELETED |
The category is no longer visible and no ads can be placed in it. It is still possible for ads to be in this category but they can no longer be found through a category search. |
Category Configuration¶
Leaf categories provide additional configuration which is provided in
config field of the category. Non-leaf categories do not provide that field.
Key |
Type |
Deprecated in |
Constraints |
Info |
|---|---|---|---|---|
priceTypes |
set<string> |
not empty |
The list of available Price Types for this category. |
|
bidMicros |
interval |
|
Allowed bid value in micros for ads in this category. |
|
totalBudgetMicros |
interval |
|
Allowed range for total budget in micros for ads in this category. |
|
dailyBudgetMicros |
interval |
|
Allowed range for daily budget in micros for ads in this category. |
|
activeAds |
interval |
|
Allowed range of active ads per seller in this category. |
|
images |
interval |
|
Allowed range of images count for ads in this category. |
|
titleLength |
interval |
|
Allowed range of the title length for ads in this category. |
|
descriptionLength |
interval |
|
Allowed range of the description length for ads in this category. |
|
shippingOption |
string |
not empty |
If |
|
tags |
map<locale, set<string>> |
Optional localized set of additional keywords that are indexed with ads in this category. |
||
verticals |
set<string> |
Optional set of verticals (groups) this category belongs to. The following verticals are
allowed: |
||
region |
string |
not empty |
If |
|
relatedPaths |
set<string> |
Optional set of paths from related existing categories used for search strategies and/or fallback scenarios to expand the search parameters when too few results are returned. |
||
priceUnits |
map<string, map<locale, string>> |
Optional set of localized price units like |
||
currency |
string |
V5 |
not empty |
The ISO 4217 currency code. Currency code is the same for all categories. |
cpc |
interval |
V5 |
|
CPC value for ads in this category. Deprecated, use bidMicros instead. |
totalBudget |
interval |
V5 |
|
Total budget for ads in this category. Deprecated, use totalBudgetMicros instead. |
minDailyBudget |
int |
V5 |
|
Min daily budget for ads in this category. Default is 0 == no daily budget.
Max should be |
paypalEnabled |
bool |
V5 |
If |
|
paypalBpEnabled |
bool |
V5 |
If |
|
suggestedCpcForPageOne |
int |
V5 |
The estimated CPC (in cents) the current user needs to set on a new ad in this category to be placed on page 1 for a browse action in the leaf category. |
Intervals¶
Parameters which are defined as type interval use one of the ISO 31-11 notations for
describing intervals. The supported notation is [a,b], (a,b), (a,b]
and [a,b). a and b must be valid numbers.
Locales¶
Categories have support for multiple locales. A locale is defined as language[_territory].
The language is defined as a ISO 639 language code and the territory is a
ISO 3166-1 alpha-2 country code. Some examples are:
nl_NL, nl_BE, fr_BE, en_US, en_AU
The locales parameter defines for which locale a category is available.
This allows for region specific differences within the same taxonomy tree.
If the locales parameter contains multiple entries then all multi-lingual fields
of type map<locale,...> have entries for all of these locales.
Price Types¶
Each leaf category has one or more price types configured which define the payment options the seller wants to offer. The valid list of price types is:
Price type |
Price required |
Description |
|---|---|---|
BIDDING |
no |
Request a bid on the ad starting from price 0. |
BIDDING_FROM |
yes |
Request a bid with a starting price > 0. |
FIXED_PRICE |
yes |
Request a fixed price. |
NEGOTIABLE |
no |
Request a negotiation between buyer and seller. |
SEE_DESCRIPTION |
no |
Additional information is in the description of the ad. |
SWAP |
no |
Request an exchange of one item for another. |
CREDIBLE_BID |
no |
Request for any reasonable offer. |
ON_DEMAND |
no |
Price is communicated on request. |
NOT_APPLICABLE |
no |
Price is not applicable for this ad. |
RESERVED |
no |
Flag for transaction in progress. |
Data Model¶
The data model is designed to support the following use cases:
render a user interface for placing an ad
validate an ad that is placed via the Sellside API
The category tree is provided as a JSON object which has the following structure:
{
"links": {
"self": "/api/sellside/category/0"
},
"id": 0,
"parentId": -1,
"level": 0,
"path": "0",
"label": {
"nl_NL": ""
},
"breadcrumbs": {},
"status": "ACTIVE",
"children": [
{
"links": {
"self": "/api/sellside/category/1"
},
"id": 1,
"parentId": 0,
"level": 1,
"path": "1",
"label": {
"nl_NL": "Antiek en Kunst"
},
"breadcrumbs": {
"nl_NL": [
"Antiek en Kunst"
]
},
"status": "ACTIVE",
"children": [
...
]
},
...
]
}
Ads can only be placed in leaf categories and leaf objects contain the full configuration for this category.
Non-Leaf Categories¶
Non-leaf categories only serve as parent nodes for lower level categories. Ads cannot be placed within them and therefore they have no configuration related to ad placement.
Field |
Type |
Constraints |
Info |
|---|---|---|---|
links |
map<string,string> |
not empty |
A link to the current category and if level > 1 a link to the parent category. |
id |
long |
|
Unique category id. |
parentId |
long |
|
Id of the parent category. |
level |
int |
|
Level at which the category is defined. |
path |
string |
not empty |
Ids of all ancestors (except the root) and the current category separated by |
locales |
list<locale> |
not empty |
Locales for which the category is available. |
label |
map<locale,string> |
one entry per locale |
Display name of the category. |
breadcrumbs |
map<locale,list<string>> |
one list per locale |
Labels of all of the ancestors (except the root) and the current category. |
status |
string |
not empty |
One of |
children |
list<category> |
not empty |
Ordered list of child categories. |
Example:
{
"links": {
"self": "/api/sellside/category/856"
},
"id": 856,
"parentId": 0,
"level": 1,
"path": "856",
"label": {
"nl_NL": "Vakantie"
},
"breadcrumbs": {
"nl_NL": [
"Vakantie"
]
},
"status": "ACTIVE",
"children": [
...
]
}
Leaf Categories¶
Leaf categories are the categories where ads can be placed. They have by definition no children. Leaf categories contain the full configuration for ads placed in this category.
Field |
Type |
Constraints |
Info |
|---|---|---|---|
links |
map<string,string> |
not empty |
Links to the current category and to the parent category. |
id |
long |
|
Unique category id. |
parentId |
long |
|
Id of the parent category. |
level |
int |
|
Level at which the category is defined. |
path |
string |
not empty |
Ids of all ancestors (except the root) and the current category separated by |
locales |
list<locale> |
not empty |
Locales for which the category is available. |
label |
map<locale,string> |
one entry per locale |
Display name of the category. |
breadcrumbs |
map<locale,list<string>> |
one list per locale |
Labels of all of the ancestors (except the root) and the current category. |
status |
string |
not empty |
One of |
suggestedCpcForPageOne |
int |
only included for root of category tree |
Suggested CPC value in (euro/dollar) cents for this ad to be shown on page one. |
config |
config |
not empty |
The category configuration |
attributeGroups |
list<attributeGroup> |
Ordered list of attribute groups. |
Attribute Groups¶
Attribute groups combine a list of attributes with a label and an optional tooltip.
Multiple attribute groups allow the user interface to render multiple groups in
separate blocks. Expect that attributes are rendered in the order given therefore
the order in the attributes field matters. The same applies to the order of the
attribute groups themselves.
Field |
Type |
Constraints |
Info |
|---|---|---|---|
label |
map<locale,string> |
one entry per locale |
Localized label of the group. |
tooltip |
map<locale,string> |
one entry per locale |
Optional tooltip/help text for the label. Can be empty. |
attributes |
list<attribute> |
not empty |
Ordered list of attributes. |
Attributes¶
Attributes define additional fields for ads in this category. The configuration
parameters allow to render the attribute in a certain way depending on the
type and the content of the values field. See Attribute Rendering below.
Field |
Type |
Constraints |
Info |
|---|---|---|---|
key |
string |
not empty, unique in category |
Attribute key. |
label |
map<locale,string> |
one entry per locale |
Localized label of the attribute. |
tooltip |
map<locale,string> |
one entry per locale |
Optional tooltip/help text for the label. Can be empty. |
type |
string |
not empty |
One of |
values |
map<locale,list<string>> |
Localized values for the attribute. The length of the JSON representation of all values for one locale must not exceed 512 bytes. |
|
defaults |
map<locale,string> |
Localized default value for required attributes. |
|
mandatory |
bool |
If |
|
searchable |
bool |
If |
|
updatable |
bool |
If |
|
writable |
bool |
If |
|
identifying |
bool |
Whether this attribute could serve as an identifier for the entire item sold. This can be used in combination with POST /ad/prefill, where you can potentially get a sample title, description and additional attributes based on 3rd party databases. |
|
precision |
int |
|
Precision for |
range |
interval |
Range for |
|
length |
interval |
|
Length range for |
prefix |
map<locale,string> |
|
Optional localized prefix for rendering. Default is empty. |
postfix |
map<locale,string> |
|
Optional localized postfix for rendering. Default is empty. |
hints |
list<string> |
Optional list of rendering hints. |
Attribute Rendering¶
How the attribute is rendered and which result type the selected value has depends on
the combination of the type and the values parameters. The following table lists
the valid combinations.
The hints field can provide additional information on how to render the field. For example,
a text input field should be rendered as a textarea field or rich text input field.
The list of rendering hints still needs to be provided.
Type |
Values |
Result Type |
Rendering |
Info |
|---|---|---|---|---|
STRING |
empty |
string |
text input |
Free text input field of |
STRING |
not empty |
string |
drop-down |
Single select field. |
LIST |
not empty |
list<string> |
check boxes |
Multi select field. |
NUMBER |
empty |
int or float |
text input |
Numeric input field with a value defined by |
BOOL |
not empty |
string |
radio buttons |
Boolean input field. |
Below is a complete example of a leaf category:
{
"links": {
"parent": "/api/sellside/category/856",
"self": "/api/sellside/category/863"
},
"id": 863,
"parentId": 856,
"level": 2,
"path": "856_863",
"label": {
"nl_NL": "Vakantiehuizen | Duitsland"
},
"breadcrumbs": {
"nl_NL": [
"Vakantie",
"Vakantiehuizen | Duitsland"
]
},
"status": "ACTIVE",
"config": {
"bidMicros": "[10000,2500000]",
"totalBudgetMicros": "[5000000,200000000000]",
"dailyBudgetMicros": "[1000000,200000000000]",
"activeAds": "[0,7000]",
"titleLength": "[1,60]",
"descriptionLength": "[1,20000]",
"images": "[1,24]",
"urlMandatory": false,
"shippingOption": "DISABLED",
"priceTypes": ["FIXED_PRICE", "BIDDING_FROM", "SEE_DESCRIPTION"],
"priceUnits": {
"per_night": {
"nl_NL": "per nacht"
}
},
"verticals": [
"VACATIONS"
],
"tags": {
"nl_NL": [
"vakantiehuis"
]
},
"relatedPaths": [
"856_892",
"856_862"
]
},
"attributeGroups": [
{
"label": {
"nl_NL": "Kenmerken"
},
"tooltip": {
"nl_NL": "Geef hier welk type advertentie u gaat maken en wat de conditie van uw product is"
},
"attributes": [
{
"key": "region",
"label": {
"nl_NL": "Regio"
},
"tooltip": {},
"type": "STRING",
"values": {
"nl_NL": [
"Sauerland",
"Beieren",
"Berlijn",
"Eifel",
"Harz",
"Moezel",
"Noord-Duitsland",
"Oost-Duitsland",
"Zwarte Woud",
"Overige regio's"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "type",
"label": {
"nl_NL": "Type"
},
"tooltip": {},
"type": "STRING",
"values": {
"nl_NL": [
"Appartement",
"Boerderij of Cottage",
"Chalet, Bungalow of Caravan",
"Landhuis of Villa",
"Overige typen"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "situated",
"label": {
"nl_NL": "Ligging"
},
"tooltip": {},
"type": "STRING",
"values": {
"nl_NL": [
"Dorp",
"Stad",
"Landelijk",
"Recreatiepark",
"Overige"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "surroundings",
"label": {
"nl_NL": "Omgeving"
},
"tooltip": {},
"type": "LIST",
"values": {
"nl_NL": [
"Aan zee",
"Aan meer of rivier",
"In bergen of heuvels",
"In bos",
"In wintersportgebied"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "numberOfBedrooms",
"label": {
"nl_NL": "Aantal slaapkamers"
},
"tooltip": {},
"type": "STRING",
"values": {
"nl_NL": [
"1 slaapkamer",
"2 slaapkamers",
"3 slaapkamers",
"4 of meer slaapkamers",
"Groepsaccommodatie"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "letter",
"label": {
"nl_NL": "Verhuurder"
},
"tooltip": {},
"type": "STRING",
"values": {
"nl_NL": [
"Eigenaar",
"Bemiddelingsbureau"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "extras",
"label": {
"nl_NL": "Extra's"
},
"tooltip": {},
"type": "LIST",
"values": {
"nl_NL": [
"Afwasmachine",
"Airconditioning",
"Huisdier toegestaan",
"Internet",
"Kinderbed",
"Open haard",
"Rolstoelvriendelijk",
"Sauna of Jaccuzi",
"Speeltuin",
"Tuin",
"Tv",
"Wasmachine",
"Zwembad"
]
},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": null,
"length": null,
"prefix": {},
"postfix": {},
"hints": []
},
{
"key": "numberOfPersons",
"label": {
"nl_NL": "Aantal personen"
},
"tooltip": {},
"type": "NUMBER",
"values": {},
"defaults": {},
"mandatory": false,
"searchable": true,
"updatable": true,
"writable": true,
"identifying": false,
"precision": 0,
"range": "[1,99]",
"length": null,
"prefix": {},
"postfix": {
"nl_NL": "personen"
},
"hints": []
}
]
}
]
}