Overview¶
The Marktplaats and 2dehands/2ememain API is a RESTful API to place ads on Marktplaats, 2dehands.be or 2ememain.be.
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:
- The locale specificed in the locale field
- The locale specified in the preferences of the current user
- 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’ |