Categories for the basic taxonomy in which advertisements on Marktplaats are placed. They represent a context for the advertisements and allow for structure.

The Categories resource makes the Marktplaats categories structure available to the API user. There are L1 and L2 categories. L1 categories group several L2 categories. Advertisements can only be placed in L2 categories.

The category structure is read-only.


Each category has a unique identifier by which it can be retrieved and a set of fields which are listed below:

field type constraints default Req W U
categoryId int positive yes no no
name string max. 70 characters yes no no
labels object yes no no
status string either open or closed, where open is the normal state for a category. yes no no


Unique reference to a Marktplaats category.


The descriptive name of the category. Deprecated: Use labels instead.


The localized descriptive names of the category, keyed by locale.


When open, it is possible to place new advertisements in this category. When status is closed, it is not possible to place new advertisements in this category and an error will be returned when tried.


name availability embedded cardinality
mp:category-attributes Category is a L2 category. no 1
mp:category-fees Category is a L2 category. no 1
up Category is a L1 category. no 1
mp:category If there are child categories yes 0..N


GET /v1/categories

This URL returns all categories.

GET /v1/categories/{categoryId}

This URL returns a L1 category, and embeds its children. No advertisements can be placed in this category.

GET /v1/categories/{l1CategoryId}/{l2CategoryId}

This URL returns a L2 category. You can place advertisements in this category.

GET /v1/categories?categoryId={categoryId}

This URL returns a L1 or L2 category, and embeds its children if present.


http error code description
404 category-not-found The category does not exist.


Retrieving a sub category :

Request :

GET /v1/categories/1/2 HTTP/1.1

Response :

HTTP/1.1 200 OK
Content-Type: application/json

  "_links": {
    "self": {
      "href": "/v1/categories/1/2"
    "find": {
      pom"href": "/v1/categories{?categoryId}",
      "templated": true
    "describedby": {
      "href": ""
    "curies": [
        "href": "{rel}.html",
        "templated": true,
        "name": "mp"
    "up": {
      "href": "/v1/categories/1"
    "mp:category-attributes": {
      "href": "/v1/categories/1/2/attributes"
    "mp:category-fees": {
      "href": "/v1/categories/1/2/fees"
  "categoryId": 2,
  "name": "Antiek | Bestek",
  "labels": {
      "nl-NL": "Antiek | Bestek"
  "status": "open"