.. index:: Categories, Attributes

.. _category_attributes:

Category attributes
===================

The Marktplaats API supports attributes for both categories and
:ref:`advertisements <attributes>` to specify additional properties of a product like *size* and
*color*.

Category attributes are recommended attribute names and values for a given
category. They help constructing automatic user interfaces in which sellers
can select one or more values from a pre-defined list of attributes.

They serve as a basis for the attributes the seller can supply in addition
to his own user-defined attributes. You cannot post/put category attributes.

There is a separate :ref:`url <category_attributes_end_point>` available to get a category attributes.


.. apifields::
    .. apifield::
        :name: key
        :type: string
        :required: true
        :constraints: --
        :description: Unique name of an attribute.

    .. apifield::
        :name: label
        :type: string
        :required: true
        :constraints: --
        :description: The label of the attribute. *Deprecated*: Use labels instead.

    .. apifield::
        :name: labels
        :type: object
        :constraints: --
        :required: true
        :description: The localized descriptive names of the attribute, keyed by locale.

    .. apifield::
        :name: type
        :type: :ref:`Attribute type <attribute_types>`
        :required: true
        :constraints: --
        :description: The label of the attribute

    .. apifield::
        :name: values
        :type: array(string)
        :required: false
        :constraints: --
        :description: A list of all allowed values for the attribute. *Deprecated*: Use options instead.

    .. apifield::
        :name: options
        :type: array(:ref:`ValueOption type <value_options>`)
        :required: false
        :constraints: --
        :description: A list of all allowed values for the attribute.

    .. apifield::
        :name: minValue
        :type: number
        :required: false
        :constraints: applicable to attribute with type NUMBER only
        :description: Minimum allowed value.

    .. apifield::
        :name: maxValue
        :type: number
        :required: false
        :constraints: applicable to attribute with type NUMBER only
        :description: Maximum allowed value.

    .. apifield::
        :name: unit
        :type: string
        :required: false
        :constraints: applicable to attribute with type NUMBER only
        :description: Indicates the unit of a NUMBER attribute. *Deprecated*: Use units instead.

    .. apifield::
        :name: units
        :type: object
        :constraints: --
        :required: true
        :description: The localized descriptive units of the attribute, keyed by locale.

    .. apifield::
        :name: mandatory
        :type: boolean
        :required: true
        :constraints: --
        :description: Indicates if attribute is mandatory or can be omitted.

    .. apifield::
        :name: searchable
        :type: boolean
        :required: true
        :constraints: --
        :description: Indicates if you can filter listing results based on this field.

    .. apifield::
        :name: writable
        :type: boolean
        :required: true
        :constraints: --
        :description: Indicates if you can set this attribute when creating an advertisement for this category

    .. apifield::
        :name: updateable
        :type: boolean
        :required: true
        :constraints: --
        :description: Indicates if you can update this attribute for advertisements created in this category

.. _attribute_types:

**Allowed attribute types**

========    ===========================================================================
type        description
========    ===========================================================================
STRING      User can select a single value from  **values**.
LIST        User can select one or more values from **values**.
NUMBER      User can provide an integer number between **minValue** and **maxValue**.
DOUBLE      User can provide a floating point number
========    ===========================================================================

.. _value_options:

**Possible value options**

A list of all allowed values for the attribute.

.. apifields::
    .. apifield::
        :name: key
        :type: string
        :required: true
        :constraints: --
        :description: Unique key of a value option.
    .. apifield::
        :name: labels
        :type: object
        :constraints: --
        :required: true
        :description: The localized descriptive labels of the value option, keyed by locale.

Reference
---------

.. _category_attributes_end_point:

.. endpoint:: GET /v1/categories/{l1CategoryId}/{l2CategoryId}/attributes

This urls returns attributes for the specified leaf category.


Example
-------

.. include:: examples/category-attributes.rst