The Guide

How to get started

The API offers the Volkswagen product data catalog, and resources to configure a car in an iterative manner.

Before you start, please be aware of the structure, this API is using:

  • Markets: e.g. Germany
  • Brands: e.g. Volkswagen
  • Models: e.g. the Golf
  • Types: e.g. Golf Trendline 1.0 TSI 63 kW 5-Gang
  • Options: e.g. App-Connect and "Volkswagen Media Control"

In order to maintain an adequate service level of OKAPI, the API endpoints incorporate a throttling mechanism that will limit the requests by an application to a reasonable amount per day.

To give you transparency about the remaining requests you are allowed to issue, we will send the throttling information in the following response headers of every request:

header description
X-Ratelimit-Limit the total amount of requests allowed
X-Ratelimit-Remaining the remaining amount of requests
X-Ratelimit-Reset time stamp, when your X-Ratelimit-Limit will be reset

Request client credentials

If you want to get access to the OKAPI, please send us an email:

Within the next days you receive an email with your client credentials in detail your client_id and your client_secret.

Request an Access token

POST
https://identity.vwgroup.io/oidc/v1/token?grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
Content-Type application/x-www-form-urlencoded

To obtain access to the OKAPI HTTP service we use the OAuth2 client credentials grant to provide an access_token.
The access_token provides access to the OKAPI services. It expires after one hour.
Please ensure that your backend application handles the lifecycle of the access token. More information about access_tokens can be found in the official OAuth spec: https://tools.ietf.org/html/rfc6749#section-1.4.

To request the access_token you have to provide the client_id and your client_secret.

You will need the access_token for every subsequent request to okapi. It will expire after one hour.

Toggle arrow Example Request with cURL...

Request
curl \
-H "Cache-Control: no-cache" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=<client_id>" \
-d "client_secret=<client_secret>" \
-X POST https://identity.vwgroup.io/oidc/v1/token
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"access_token":"<access_token>",
"token_type":"bearer",
"expires_in":3600,
"user_id":"<client_id>"
}

Utilise the resources

The API offers a selection of catalag and configuration endpoints. The catalog endpoints provide static data containing the productdata. The configuration endpoints provide the ability to iteratively store and configure a car.


The Product data catalog

The product data catalog provides static data about supported countries, available models, types and options.

Keep up to date

All catalog endpoints are responding with an etag header that shows you current version of the provided product data. Whenever we are updating parts of the provided product data, the etag value will change.

Response header:

header description
ETag The identifier for a specific version of a catalog resource.

If you provide the etag value as request header (if-none-match) and the data has not changed, all catalog resources will respond with the http status code 304 not modified.

Request header:

header description
If-None-Match Your stored ETag hash of a former request.

List all countries

GET
https://api.productdata.vwgroup.com/v2/countries
Authorization Bearer {access_token}
Accept application/json

Toggle arrow Example Request with cURL...

Request
curl \
-X GET https://api.productdata.vwgroup.com/v2/countries \
-H "Authorization: bearer <access_token>" \
-H "Accept: application/json"
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"countryCode": "BE",
"name": "Belgium"
},
{
"countryCode": "CH",
"name": "Switzerland"
}
],
"meta": {}
}

List all brands

GET
https://api.productdata.vwgroup.com/v2/catalog/{country_code}/brands
Authorization Bearer {access_token}
Accept application/json

Toggle arrow Example Request with cURL...

Request
curl \
-X GET https://api.productdata.vwgroup.com/v2/catalog/CH/brands \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"brand_id": "d3f207e5-18d8-5bd2-a5fa-a1acc05629fa",
"name": "Volkswagen PKW"
}
],
"meta": {}
}

List all models

GET
https://api.productdata.vwgroup.com/v2/catalog/{country_code}/brands/{brand_id}/models
Authorization Bearer {access_token}
Accept application/json

By brand and country

Toggle arrow Example Request with cURL...

Request
curl \
-X GET https://api.productdata.vwgroup.com/v2/catalog/DE/brands/d3f207e5-18d8-5bd2-a5fa-a1acc05629fa/models \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": "ef7f7c23-2537-5067-9c0b-25f77433a1de",
"name": "The up!",
"code": "30450_30100"
},
{
"id": "8cd99132-b085-5188-88fb-b7e3a86a336f",
"name": "Der Polo",
"code": "30100_30203"
},
{
"id": "146a91a8-954f-520e-bb56-22ebbcb8a6d3",
"name": "Der neue T-Cross",
"code": "30100_30250"
},
{
"id": "54ae5960-4c6e-5a50-9f36-c88ab444db21",
"name": "Der Golf",
"code": "30100_30315"
}
],
"meta": {}
}

List all types by brand

GET
https://api.productdata.vwgroup.com/v2/catalog/{country_code}/brands/{brand_id}/types
Authorization Bearer {access_token}
Accept application/json

By country and brand

Toggle arrow Example Request with cURL...

Request
curl \
-X GET https://api.productdata.vwgroup.com/v2/catalog/DE/brands/d3f207e5-18d8-5bd2-a5fa-a1acc05629fa/types \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": "8632ad57-6147-54ce-a3a8-d7285373f257",
"name": "high up!(#) 1.0(#) 55 kW(#) 5-Gang(#)",
"base_type": "1224DV",
"model_year": "2019",
"version": "1",
"code": "TYPE:1224DV-GYOIYOI,"
"extensions": ["
{
"id": "d0876daf-1f03-5c62-b683-149cba339e7c",
"category": "PACKET",
"code": "YOI",
"description": "Volkwagen Connect"
}
]
}
],
"meta": {}
}

List the types of a model

GET
https://api.productdata.vwgroup.com/v2/catalog/{country_code}/models/{model_id}/types
Authorization Bearer {access_token}
Accept application/json

By country and model

Toggle arrow Example Request with cURL...

Request
curl \
-X GET https://api.productdata.vwgroup.com/v2/catalog/DE/models/127b6237-08ca-54d4-895f-0d23e654257b/types \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": "8277133f-963a-584a-815d-1a92bbfa4574",
"name": "(#) DC Highline(#) 3.0 V6 TDI EU6 SCR 4MO BMT(#) 150 kW(#) AG8-Gang(#)",
"base_type": "S6BC6A",
"model_year": "2019",
"version": "1",
"code": "TYPE:S6BC6A-MAHLEX1-GWF2WF2-GZSBZSB-MVBK1T9-MVZU6B4,"
"extensions": ["
{
"id": "2b7759a4-32ce-5aa7-9ff1-0f2570b05186",
"category": "AHL",
"code": "EX1",
"description": "Anhängelast 3.500 kg"
}
]
}
],
"meta": {}
}

List the options of a type

GET
https://api.productdata.vwgroup.com/v2/catalog/{country_code}/types/{type_id}/options
Authorization Bearer {access_token}
Accept application/json

By type

Toggle arrow Example Request with cURL...

Request
curl \
-X GET https://api.productdata.vwgroup.com/v2/catalog/DE/types/cb6df056-1638-5c21-8e3e-7461556bdba0/options \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json"
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": [
{
"id": "50295e4c-25ec-5006-a38c-9c467921e1cd",
"category": "COLOR_EXTERIEUR",
"code": "B4A1",
"description": "white black",
"classification": "OPTIONAL_EQUIPMENT"
},
{
"id": "e607026d-921d-521a-906b-8d799d39cdd1",
"category": "COLOR_EXTERIEUR",
"code": "G2A1",
"description": "red black",
"classification": "OPTIONAL_EQUIPMENT"
},
{
"id": "44fe0f1f-c1d1-50a4-9062-108b8c7de7cb",
"category": "COLOR_EXTERIEUR",
"code": "G2B4",
"description": "red white",
"classification": "OPTIONAL_EQUIPMENT"
}
],
"meta": {}
}

Configure a car

In order to get started configuring a car, you might want to do the following:

  • Select a country
  • Select a brand
  • Select a model
  • Create a configuration

So you created your configuration object which is just in need of a model_id. Now you can iteratively manipulate it or receive information about it:

  • Show choices of options for your configuration
  • Select or remove options
  • Gather links for pictures of the current configuration
  • Check your configuration
  • Gather wltp values

To configure a car iteratively you have to create a configuration which you can utilise afterwards to gather valid options, add or remove them, or retrieve other information about this particular configuration.

Every configuration will be cached for you for 24h after your last modification.

Create a configuration

POST
https://api.productdata.vwgroup.com/v2/configurations
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

A configuration can be created starting with a model id, but you are free to also provide options from the start, if you are able to already provide a configuration.

The call will respond with the created configuration containing the configuration's uuid that has to be used for further manipulations.

Gather the choices of options

GET
https://api.productdata.vwgroup.com/v2/configurations/{configuration_id}/choices
Authorization Bearer {access_token}
Accept application/json

At every point within the configuration process you can request the list of choices. A choice contains options that are either valid or invalid within the current configuration. Beside this information a choice defines a category/domain of a given configuration that can be customised with options that are provided.

Add or remove options

POST
https://api.productdata.vwgroup.com/v2/configurations/{configuration_id}/options
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

You can add one option by providing the option entity within the POST body. The resource will respond with the actual set of options.

DELETE
https://api.productdata.vwgroup.com/v2/configurations/{configuration_id}/options/{option_id}
Authorization Bearer {access_token}

You can delete one option per request from your configuration by providing the option id as path variable. The resource will respond with a 204 if the request succeeds.

PUT
https://api.productdata.vwgroup.com/v2/configurations/{configuration_id}/options
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

You can replace the set of options of your configuration by providing the new array of options as body within the PUT request.

Complete a configuration

GET
https://api.productdata.vwgroup.com/v2/configuration/{configuration_id}/options?resolve=true
Authorization Bearer {access_token}
Accept application/json

To complete a partial configuration to a fully equipped and buildable car, you can use the resolve function of the options endpoint.
We will amplify the given set of options with a selection of options that will make your current partial configuration a distinct one. The request responds with an array of options that will make out a distinct configuration. The given configuration will not be manipulated by this request, in order to change your configuration you will have to replace the options of your current configuration with the array of options provided. The options added to the configuration's set of options will provide just one random example of how a partial configuration might be extended to gather a distinct configuration. If your configuration has already been distinct the response will just contain your configuration's options.

Repair a configuration

GET
https://api.productdata.vwgroup.com/v2/configuration/{configuration_id}/options?recover=true
Authorization Bearer {access_token}
Accept application/json

To recover a configuration that is not buildable, you can call the options endpoint providing the request parameter recover.
We will search for options that are conflicting with your current selection of options but valid options within the model. The request responds with an array of options that will make out the options that should be removed in order to recover the given configuration. If the configuration contains options, that are not valid within the given model, the resource will respond with a 409.

Check the configuration

GET
https://api.productdata.vwgroup.com/v2/configuration/{configuration_id}/check
Authorization Bearer {access_token}
Accept application/json

At every point within the configuration process you can check whether the given configuration is buildable or not. and whether the given configuration is distinct.

So what do we mean if we talk about a distinct configuration: If you provide a partial configuration, and the combination of options is buildable, there might be several options, on how a car could be build.

A distinct configuration defines enough options to make out just one vehicle. We will always try to autocomplete a partial configuration, but in order to identify a single buildable vehicle we need as many options as it takes that there could be just one version of a vehicle left: In the example the selection of the red hubcap just leaves one option to build that vehicle.

!
If you want to speed up the buildability check, you can provide the request parameter ?distinct=false, to skip the distinct check.

Operations

These intent resources provide some basic functionality to interact with consumer provided configurations.

Check a given configuration

POST
https://api.productdata.vwgroup.com/v2/operation/{country_code}/check
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

Check the buildability for a given configuration.
The response contains the information whether the given configuration is buildable and distinct.
A configuration is buildable if the configuration defines an assortment of options, that can be contained in one or more vehicles which can be produced

So what do we mean if we talk about a distinct configuration: If you provide a partial configuration, and the combination of options is buildable, there might be several options, on how a car could be build.

A distinct configuration defines enough options to make out just one vehicle. We will always try to autocomplete a partial configuration, but in order to identify a single buildable vehicle we need as many options as it takes that there could be just one version of a vehicle left: In the example the selection of the red hubcap just leaves one option to build that vehicle.

!
If you want to speed up the buildability check, you can provide the request parameter ?distinct=false, to skip the distinct check.

Toggle arrow Example Request with cURL...

Request
curl \
-X POST \
-H "Authorization: bearer <access_token>" \
-H "Cache-Control: no-cache" \
-H "Content-Type: application/json" \
-d "{ \"brand_id\": \"V\",\"model_id\": \"36c170df-178b-5b46-a3f7-94fc2920e79f\",\"options\": [ {\"id\":\"45f0bc1e-0c9b-5eb7-9608-25d6ccb2a6c0\"}, {\"id\":\"COLOR_EXTERIEUR:0Q0Q\"}, {\"id\":\"COLOR_INTERIEUR:XE\"}, {\"id\":\"PACKET:PSA\"}, {\"id\":\"PACKET:PAF\"}]}" \
https://api.productdata.vwgroup.com/v2/operation/CH/check
Response
HTTP/2.0 200 OK
Content-Type: application/json
{ "buildable": true, "distinct": false }

WLTP data for a given configuration

POST
https://api.productdata.vwgroup.com/v2/operation/{country_code}/wltp
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

Request the WLTP values for a configuration. In order to request the WLTP values the given configuration has to be distinct. You can always call the check resource in order to assure that the configuration is distinct, before issuing a call to request the wLTP values..

Toggle arrow Example Request with cURL...

Request
curl \
-X POST \
-H "Authorization: bearer <access_token>" \
-H "Cache-Control: no-cache" \
-H "Content-Type: application/json" \
-d "{ \"brand_id\": \"d3f207e5-18d8-5bd2-a5fa-a1acc05629fa\",\"model_id\": \"54ae5960-4c6e-5a50-9f36-c88ab444db21\",\"options\": [ {\"id\":\"e6ce0e6e-d1fa-5857-b857-31101f1b1520\"}, {\"id\":\"947374b8-61df-5217-b42a-35271b3eb695\"}, {\"id\":\"dc7e7c77-ba62-5529-b126-b9b340502f75\"}]}" \
https://api.productdata.vwgroup.com/v2/operation/CH/wltp
Response
HTTP/1.1 200 OK
Content-Type: application/json

BODY:
[
{
"data_version": "11",
"engine_type": "ICE",
"fuel_types": [
"PETROL"
],
"general_data": {
"values": [
{
"key": "MASS_ACTUAL",
"value": 1077.075,
"unit": "kg"
}
]
},
"calc_algorithm": "RLF",
"tire": {
"front": {
"eeclass": "B",
"category": "C1"
},
"rear": {
"eeclass": "B",
"category": "C1"
}
},
"cycle_modifications": {
"values": []
},
"interpolations": [
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "LOW",
"value": 6.893411017872731,
"unit": "l/100km"
},
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "MEDIUM",
"value": 5.1990300132965865,
"unit": "l/100km"
},
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "HIGH",
"value": 4.828425094020777,
"unit": "l/100km"
},
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "EXTRA_HIGH",
"value": 5.970061373915594,
"unit": "l/100km"
},
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "COMBINED",
"value": 5.59022076225368,
"unit": "l/100km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "LOW",
"value": 156.7438669817635,
"unit": "g/km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "MEDIUM",
"value": 118.14483328190443,
"unit": "g/km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "HIGH",
"value": 109.70216236113592,
"unit": "g/km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "EXTRA_HIGH",
"value": 135.69813961073,
"unit": "g/km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "COMBINED",
"value": 127.06325787413448,
"unit": "g/km"
}
],
"nedc": {
"values": [
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "COMBINED",
"value": 4.8,
"unit": "l/100km"
},
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "EXTRAURBAN",
"value": 4.1,
"unit": "l/100km"
},
{
"value_type": "CONSUMPTION",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "URBAN",
"value": 6,
"unit": "l/100km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "COMBINED",
"value": 110,
"unit": "g/km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "EXTRAURBAN",
"value": 94,
"unit": "g/km"
},
{
"value_type": "CO2",
"fuel_type": "PETROL",
"energy_management_type": "PURE",
"phase": "URBAN",
"value": 137,
"unit": "g/km"
}
]
},
"energy_efficiency": {
"class_nedc": "C",
"iso": "DEU"
}
}
]

Complete a given configuration

POST
https://api.productdata.vwgroup.com/v2/operation/{country_code}/resolve
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

To complete a partial configuration to a fully equipped and buildable car, you can use the resolve function of the options endpoint.
We will amplify the given set of options with a selection of options that will make your current partial configuration a distinct one. The request responds with a completed and distinct configuration. The options added to the configuration's set of options will provide just one random example of how a partial configuration might be extended to gather a distinct configuration. If your configuration has already been distinct the response will just contain the given configuration.

Recover a given, not buildable configuration

POST
https://api.productdata.vwgroup.com/v2/operation/{country_code}/recover
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

To recover a given configuration that is not buildable, okapi will search for options that are conflicting with your current selection of options but valid options within the model. The request responds with a recovered configuration. If the configuration contains options, that are not valid within the given model, the resource will respond with a 409.

Gather the choices of options of a given configuration

POST
https://api.productdata.vwgroup.com/v2/operation/{country_code}/configure
Authorization Bearer {access_token}
Content-Type application/json
Accept application/json

At every point within the configuration process you can request the list of choices. A choice contains options that are either valid or invalid within the current configuration. Beside this information a choice defines a category/domain of a given configuration that can be customised with options that are provided.


FAQ

How we create uuids

We are using the uuid Version 5 which is a standard uuid calculated by a namespace and a name, in order to provide the ability to calculate uuids in a deterministic way, utilising the id/qualifiers of the former data tree.
UUID V5 offers different modes to calculate a uuid we are using the namespaceMode URL in order to calculate a root hash from the project's URL (https://productdata.vwgroup.com). This uuid will be the parentUUID for the first level tree branches of the data, which are the brands. Every brand's uuid will use the namespaceMode UUID, therefore using the root uuid as parentUUID and the legacyBrandId (e.g. 'V' for Volkswagen) as name in order to calculate the brand's uuid. This way we are also calculating the model's uuid (using the brand's uuid as parentUUID and the legacy modelId as name), and the typeId (using the model's uuid as parentUUID and the legacy typeId as name in combination with the model year).

given a function that calculates version 5 uuid's:

uuidv5(namespaceMode::NameSpaceModeEnum, parentUUID::UUID, name::String) uuid:UUID {...}

The process to create the uuids:

var root UUID = uuidv5(nsMode.URL, null, 'https://productdata.vwgroup.com')
var brand UUID = uuidv5(nsMode.UUID, root, 'V')
var model UUID = uuidv5(nsMode.UUID, brand, '30450_31600')
var type UUID = uuidv5(nsMode.UUID, model, 'TYPE:1222AV-GPKBPKB-GZRGZRG-GPAFPAF-2018')

406?

We are using content negotiation. Do you?

All resources will contain a specific representation. Content negotiation determines whether the resource can be requested or provided in a specific representation. Therefore we will check every request whether the Accept header is set, and we can provide the desired representation. If the resource cannot provided in the requested representation the API will respond with a http status code 406 (Not Acceptable). If you omit the header we will fallback to the value application_json and therefore respond in json. Additionally all resource will respond with the provided representation within the header Content-Type.

If you want to get more information on content negotiation please visit the rfc specification.

Data updates?

We will update the data provided constantly. If you are storing references of our data on your side you can utilise the http ETag header to check whether the data has changed since your last request. All Catalog endpoints will respond with an ETag header which keeps a hash value of the data the resource contains. As soon as the data changes this hash will change. You can store the hash on your side and provide it as value of the If-None-Match header in every request. If you provide this header and the content has not changed, the resource will respond with a 304 (Not Modified) and no body. If the content has changed, it will respond with a 200 providing the requested response body, and the new ETag value within the header.

If you want to get more information about entity tags please visit the rfc specification (3.11 Entity Tags).

No WLTP Data?

If you are not able to receive any WLTP Data there are a few things to consider.

You have to provide a buildable configuration. To assure that your configuration is buildable please take a look at how to check whether your configuration is buildable.

You have to provide a distinct configuration, though we are just able to calculate the values if the selection of options within the given configuration point out just one single vehicle. To assure that your configuration is distinct please take a look at how we define a distinct configuration.

Additionally there is the option that no WLTP Data is available for the requested configuration, which will be indicated by 204 (Not Found) response.

Distinct?

So what do we mean if we talk about a distinct configuration: If you provide a partial configuration, and the combination of options is buildable, there might be several options, on how a car could be build.

A distinct configuration defines enough options to make out just one vehicle. We will always try to autocomplete a partial configuration, but in order to identify a single buildable vehicle we need as many options as it takes that there is just one version of a vehicle left: The first example picture shows a buildable partial configuration on the left side, which could make out three different ways to complete a vehicle that could be ordered. The selection of the red hubcap in the second picture identifies the red vehicle definitely. Therefore the selection of the given option makes out a distinct configuration.