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.
The Marketplace API allows you to:
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.
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.
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.
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.
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:
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
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.
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.
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" }
]
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" },
…
]
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.
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)
In this chapter, we will discuss some common error codes that you may encounter while working with the Marketplace API. Understanding these error codes will help you handle errors effectively and ensure a smooth user experience. The most important error codes to be aware of are 401 Unauthorized, 404 Not Found, and 500 Internal Server Error.
A 401 Unauthorized error occurs when a request to the API fails due to missing or invalid authentication credentials. This usually means that the API key is either missing, incorrect, or has expired. To resolve this error, make sure that you are including a valid API key in the request.
If you are still encountering a 401 Unauthorized error after verifying your API key, it's possible that your API key has expired or has been revoked. In this case, you will need to obtain a new API key from the API provider.
A 404 Not Found error occurs when the requested resource, such as a specific vehicle or endpoint, cannot be found. This can happen if the resource has been removed, the endpoint is misspelled, or the provided vehicle ID is invalid.
To resolve this error, double-check the requested URL and ensure that it matches the correct format as specified in the API documentation. If you are trying to retrieve a specific vehicle, the vehicle may be offline or sold and is no longer available through the API.
A 500 Internal Server Error indicates that something went wrong on the server-side while processing your request. This error is often caused by an issue with the API itself, such as a bug, a server configuration problem, or an unexpected condition.
When encountering a 500 Internal Server Error, it's generally best to retry the request after a short delay, as the issue might be temporary. If the problem persists, you should contact the API provider's support team and provide details about the error, including the requested URL, request headers, and any error messages returned by the API, and include a timestamp of when the error occurred, if possible.
This guide has provided a brief introduction to the Marketplace API, its scope, purpose, and main endpoints, as well as an overview of the technical aspects, such as its RESTful architecture and JSON result format. However, this is just the beginning, and there may be future updates and extensions to this guide as the API evolves and new features are added.
We encourage you to explore the complete API documentation for a more in-depth understanding of the available endpoints, query parameters, request methods, and error handling. The documentation will be your primary resource for successfully integrating the API into your applications.
If you need any assistance or have questions about the API, please don't hesitate to get in touch with our support team. We are here to help you make the most of the Marketplace API and ensure a smooth integration process.