Getting Started with the Marketplace API

The Marketplace API is designed to provide an easy and efficient way for developers to search the vehicle stock of a vehicle dealer or dealer-group. In this guide, we'll cover the scope of the API, the purpose and usage of the API key, and document the main endpoints to help you get started.

Scope of the API

The Marketplace API allows you to:

• Populate the search form dropdowns with valid values, such as makes, models, years, and more.
• Perform a search based on various filters and query parameters.
• Retrieve detailed information about a specific vehicle.
• Perform example calculations for financing and/or leasing offers for a specific vehicle, by facilitating connected calculators of connected banks.
• Create search requests for a user, to be notified via e-mail of matching vehicles added in the future.
• etc.

The Marketplace API is meant to be used by vehicle dealers and dealer-groups to streamline their search process, and provide better user experience for their customers.

Technical Aspects

In this chapter, we will discuss the technical aspects of the Marketplace API, specifically its RESTful architecture and JSON result format. Understanding these aspects will help you seamlessly integrate the API into your applications and systems.

RESTful Architecture

The Marketplace API is a RESTful API, which means that it uses HTTP requests to GET, PUT, POST and DELETE data. The API is organized around RESTful resources, which are any kind of object, data, or service that can be accessed by the client.

JSON Requests and Responses

The Marketplace API accepts requests and returns results in JSON (JavaScript Object Notation) format. JSON is a lightweight, text-based data interchange format that is easy to read and write, and easy for machines to parse and generate. JSON has become the standard format for web APIs due to its simplicity and compatibility with various programming languages.

API key

To use the Marketplace API, you will need an API key that uniquely identifies your dealership or dealer-group. This API key serves two main purposes:

1. Authentication: The API key is required to authenticate your requests to the API, ensuring that only authorized clients can access the API resources.
2. Tracking: The API key allows the API to track your usage, which is important for monitoring and managing your account's access limits and quotas.

To obtain an API key, you will need to sign up to the AUTOMANAGER and activate the "Marketplace" app. The API key will be generated automatically and will be available in the "Marketplace" app settings. The key is bound to a specific domain (or list of domains), and can be used to access the API from any subdomain of the specified domain.

The API key is passed in the query string of each request, using the apikey parameter. For example:
https://api.pixel-base.de/marketplace/v3-11365/criteria/all?apikey=1234567890

Main API endpoints

The Marketplace API provides a number of endpoints to access the data. The following chapters lists the main endpoints, and provides a brief description of each.

Search Form Population

This endpoint returns a list of valid values for the search form dropdowns, such as makes, models, body types, and more.

Endpoint: /criteria/all
Method: GET
Parameters: apikey (required)
Example: https://api.pixel-base.de/marketplace/v3-11365/criteria/all?apikey=1234567890
Example response (shortened/truncated):
{
  "bodies": [
    { "isActive": true, "value": "sedan", "label": "Limousine" },
    { "isActive": true, "value": "offroad", "label": "SUV/Geländewagen/Pickup" },
    { "isActive": true, "value": "compact", "label": "Kleinwagen" },
    …
  ],
  "manufacturers": [
    { "isActive": true, "value": "219", "label": "Alfa Romeo" },
    { "isActive": true, "value": "220", "label": "Audi" },
    { "isActive": true, "value": "221", "label": "BMW" },
    { "value": "222", "label": "Chrysler" },
    …
  ],
  …
}


The value is then used for searching vehicles. Attention: For internal reasons, the values returned may differ between API keys, so it is not advised to hard-code this values into a generic solution.

Search form population (for model series)

These endpoints returns a list of model series for a specific manufacturer, if the manufacturer supports model groups (e.g. BMW will return the series 1er, 2er, 3er, 4er, etc.

Endpoint: /criteria/series
Method: GET
Parameters: apikey (required), manfacturers (required)
Example: https://api.pixel-base.de/marketplace/v3-11365/criteria/series?apikey=1234567890&manufacturers=221 (list model series for BMW)
Example response (shortened/truncated):
[
  { "isActive": true, "name": "1", "value": "1", "label": "1er" },
  { "isActive": true, "name": "2", "value": "26", "label": "2er" },
  { "isActive": true, "name": "3", "value": "2", "label": "3er" },
  { "isActive": true, "name": "4", "value": "23", "label": "4er" },
  …
  { "isActive": true, "name": "x", "value": "8,10,11,12,13,40,27,42", "label": "X" },
  { "isActive": true, "name": "z", "value": "9", "label": "Z" },
  { "name": "other", "value": "6", "label": "sonstige Modelle" }
]

Search form population (for models)

These endpoint returns a list of models for a specific manufacturer (and optional a model serie).

Endpoint: /criteria/models
Method: GET
Parameters: apikey (required), manfacturers (required), series (optional)
Example: https://api.pixel-base.de/marketplace/v3-11365/criteria/models?apikey=1234567890&manufacturers=221&series=23 (list models for BMW 4er)
Example response (shortened/truncated):
[
  { "value": "5573", "label": "418d" },
  { "isActive": true, "value": "69", "label": "420d" },
  { "isActive": true, "value": "76", "label": "420d xDrive" },
  …
]

Search for vehicles

This endpoint searches the vehicle stock according to the provided search criteria and returns a sorted, paginated list of matching vehicles.

Endpoint: /vehicles
Method: GET
Parameters: apikey (required), orderby (required), orderdir (required), skip (required), take(required), plus any search-parameter
Example: https://api.pixel-base.de/marketplace/v3-11365/vehicles?apikey=1234567890&orderby=Price&orderdir=Asc&skip=0&take=20&manufacturers=221&series=23 (list the first 20 vehicles for BMW 4er, in ascending price order)
Example response (shortened/truncated):
{
  "items": […],
  "total": 120,
  "secondaryTotal": 0
}

The total field states the total number of vehicles found for the current search. It can be used to build the paging navigation in the UI. The secondaryTotal field is used internally only and can be safely ignored.

Retrieving a single vehicle

This endpoint retrieves detailed information about a single vehicle.

Endpoint: /vehicles/{id}
Method: GET
Path elements: {id} = identifier for a single vehicle
Parameters: apikey (required)
Example: https://api.pixel-base.de/marketplace/v3-11365/vehicles/4711?apikey=1234567890 (retrieve vehicle with id = 4711)

Request limits, paging and caching

There is currently no application-side rate limit on the Marketplace API. Please still keep your request volume reasonable, the API is a shared resource. The following limits do apply:

• take is capped server-side at 1000. Larger values are silently reduced to 1000, no error is returned. Always evaluate the number of items you actually received instead of assuming the page size you asked for.
• skip and take are accepted on /vehicles and on /vehicles/ids, and the same cap applies to both.
• Responses of the vehicle endpoints are cached for 6 seconds, on the server as well as on the client (via the Cache-Control header). Repeating an identical request within that window will not return fresher data.

Keeping a local copy of the stock in sync

The API offers no "changed since" filter and no change feed. A delta is determined on the client side, by comparing against the full list of vehicle ids.

Endpoint: /vehicles/ids, called without any search parameters
Method: GET
Parameters: apikey (required)
Example: https://api.pixel-base.de/marketplace/v3-11365/vehicles/ids?apikey=1234567890
Example response (shortened/truncated):
{
  "items": [ 4711, 4712, … ],
  "itemsExt": [
    { "id": 4711, "lastEditTimestamp": "2026-03-17T18:04:03.03" },
    { "id": 4712, "lastEditTimestamp": "2026-03-19T09:12:44.517" },
    …
  ],
  "total": 120
}

Called this way the endpoint returns the complete stock and is not subject to the take limit described above. Use it as the reference for your synchronisation:

• New or changed is an id you do not know yet, or an id whose lastEditTimestamp is newer than the one you stored.
• Load the details for those ids via /vehicles/byids, for example …/vehicles/byids?apikey=1234567890&ids[0]=4711&ids[1]=4712. Request them in batches: the ids travel in the query string, so the practical batch size is bound by the maximum URL length. A few hundred ids per call is a safe size.
• Sold or withdrawn means the id has simply disappeared from the list. There is no status field and no tombstone entry, and a subsequent GET /vehicles/{id} answers with 404 Not Found.

Please note on lastEditTimestamp: the value is serialised without a time zone designator (for example 2026-03-17T18:04:03.03) and has to be read as local time in Europe/Berlin, including the daylight saving time switch. Do not parse it as UTC, and compare it only against timestamps taken from this same endpoint.

Consumption and emission figures

Every vehicle carries the flag consumptionDataRequired and the ready-made disclosure line wltpEnVkvText. Always evaluate the two together.

• consumptionDataRequired = true: the consumption and emission figures have to be disclosed for this vehicle under the German Pkw-EnVKV. wltpEnVkvText is complete and can be rendered unchanged as the mandatory disclosure.
• consumptionDataRequired = false: there is no disclosure obligation. Figures may be present, but they can be incomplete, and whether they are shown at all is a decision of the publishing channel. wltpEnVkvText should not be rendered unchecked in this case: missing values leave empty placeholders in the text, such as CO2-Emissionen (kombiniert):  g/km.

The flag pluginHybrid tells you which variant of the disclosure you are looking at. For a plug-in hybrid the figures are the weighted combined ones, and wltpEnVkvText additionally states the values with a discharged battery; for every other vehicle they are the plain combined figures. Use this flag rather than deriving it from fuel — those ids are internal and, as noted above, may differ between API keys.

The individual WLTP phase values (…Low, …Medium, …High, …ExtraHigh) are part of the model, but they are only filled where the data is maintained for the vehicle, and missing values are omitted from the JSON entirely. Expect them for a minority of the stock only, and do not build a mandatory disclosure on them.

Financing and leasing offers

A vehicle carries its offers in financingOptions and leasingOptions. Both arrays use the same model, but not every field carries the same meaning in both contexts.

• advancePayment is the down payment (Anzahlung) of a financing offer. On a leasing offer it carries the same value as specialPayment (the Sonderzahlung) and must not be evaluated as a second, separate amount.
• instalment is the monthly rate as maintained for the offer, and it is always the gross rate. On a leasing offer with target = Commercial the rate the dealer advertises is the net one, which is delivered separately as instalmentNet. Use instalmentNet for commercial leasing offers whenever it is present, and fall back to instalment otherwise — the field is omitted from the JSON when the dealer has not maintained a net rate.