Overview

The Marktplaats and 2dehands/2ememain API is a RESTful API to place ads on Marktplaats, 2dehands.be or 2ememain.be. You can interact with the api by navigating to The api explorer.

The content is provided in JSON format in UTF–8 encoding.

Multi tenant/multi locale

The API is identical for Marktplaats and 2dehands/2ememain. This means we support two platforms which have the same semantics from an API point of view, but this doesn’t mean the platforms are the same. It is only possible to place advertisements on the platform of the URL which is being used. This means it is not possible when using the Marktplaats API to place advertisements on the 2dehands platform and vice versa.

When using the 2dehands platform, it is possible to explicitly define the locale (language) of the entity by supplying a locale field. This field is optional, and when omitted, the default locale is defined using the following rules in order of priority:

  1. The locale specificed in the locale field
  2. The locale specified in the preferences of the current user
  3. The default locale for the current domain. This means nl-BE for api.2dehands.be and fr-BE for api.2ememain.be

The API’s for the 2 platforms with the allowed locales are defined below:

  • Platform Marktplaats: supported locales nl-NL, URL: api.marktplaats.nl

  • Platform 2dehands: supported locales nl-BE and fr-BE, URL’s:
    • api.2dehands.be - 2dehands platform, default locale nl-BE
    • api.2ememain.be - 2dehands platform, default locale fr-BE

While both platforms are supported, in the examples we mainly use Marktplaats. The functionality should be the same for 2dehands.

Accept Headers

Each call to resources of the API needs accept headers set. One part in that is the Media Type, as defined above. An additional part is necessary for allowing OAuth errors to be returned, in regular JSON. We recommend usage of accept headers as follows:

<Media Type>, application/json

In case of absence of the ‘application/json’ part, an OAuth error such as ‘401: Token Expired’ will not be possible to be returned since the accepted content type does not match, resulting in a ‘406: Not accepted’ error, obfuscating the underlying issue. Our examples will also demonstrate the recommended usage.

Authentication

Authentication is provided using OAuth2 to allow easy integration with existing libraries. For more information please have a look at the OAuth 2.0 website.

Dates and Times

All date/time values are specified in ISO 8601 Combined date and time in UTC format.

Prices and Currencies

All monetary amounts like prices and budgets are currently in Euros and stored as euro cents. Currencies are specified as three character ISO 4217 code.

HTTP Response Codes and Error Handling

To retrieve, update and delete resources with the API you use the standard HTTP verbs GET, PUT and DELETE. If the resource exists and the request was successful the server responds with 200 OK. If the resource does not exist the server responds with 404 Not Found.

To create a new resource you perform a POST request to which the server responds with 201 Created and a Location header containing the URL of the new resource.

All requests are validated before they are being executed by the server. If the validation fails the server responds with 400 Bad Request and an error response which contains a list of the errors. More information can be found under Error Handling.

Field definitions

Field definitions of resources follow a standard table pattern.

column name meaning
field the name of the field (when writing)
type the type of the field
constraints any constraints that apply to this field that you should know about
Req is this field required
W is this field writable (first time write (POST))
U is this field editable (PUT/PATCH)

HTTP PATCH Methods

When an HTTP PATCH method is called, the body should be formatted according to the JSON Patch RFC. The document structure of such a requests has the following structure:

[{"op":"<operation>", "path":"<path>", "value":"<value>"}]

The operation can either be add, remove, replace, move, copy or test. In the API, mainly add, remove, and replace are supported.

The path is the name of the field the operation should be applied to. For example, if one wants to change the _title_ field, the path should be /title. Note the beginning forward slash, which is an indication that this should be applied to the top level field of the document.

The value should be the value for the field. Value should only be specified for replace, add and test. For move and copy, a field called from should be used to specify the source of the operation.

Errors

http error code description
400 invalid-patch-operation The patch operation sent in the patch request is not valid. It should be one of ‘add’, ‘remove’, ‘replace’, ‘move’, ‘copy’, ‘test’