What does its look like? #

Our REST api returns type MIME: application/hal+json, GeoJson for locations data and RFC3339 for time format.

HTTP Request Verb #

The Stellantis WEB API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) are based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Moreover, the Web API uses appropriate HTTP verbs for each action:

HTTP Response #

See this page for more information about errors & rate limit.

HTTP body format #

Most of the time, the response format of the HTTP body is application/hal+json.

But in the case of the lastPosition endpoint: /vehicles/{vid}/lastPosition.
The return format is application/vnd.geo+json.

In this case the retuned object does not include the regular fields of this API but follow the GeoJSON specification.

Single Object #

When you call for a resource with an id you will retrieve a single object. Every resource which respond with a single object respect the following generic schema:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "_links": {
    "self": {
      "href": "oper"
    },
    (...)
  },
  (...)
  "createdAt": "2017-08-10T13:46:39.652+0000",
  "updatedAt": "2017-08-10T13:46:39.652+0000",
  "_embedded": {
    (...)
  }
}

Collection #

When you call an api with a plural noun you will receive an array of objects. Every resource which responds with a list of object respect the following generic schema.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
{
    "_links": {
        "self": {
            "href": (...)
        }
    },
    "total": 2,
    "_embedded": {
        "vehicles": [
            {
                "id": ,
                "vin": ,
                "brand": ,
                "pictures": [(...)],
                "_links": {
                    "alerts": {
                        "href": "(...)/user/vehicles/{id}/alerts"
                    },
                    "trips": {
                        "href": "(...)/user/vehicles/{id}/trips"
                    },
                    "self": {
                        "href": "(...)/user/vehicles/{id}?locale=fr-FR"
                    },
                    "lastPosition": {
                        "href": "(...)/user/vehicles/{id}/lastPosition"
                    },
                    "telemetry": {
                        "href": "(...)/user/vehicles/{id}/telemetry"
                    },
                    "maintenance": {
                        "href": "(...)/user/vehicles/{id}/maintenance"
                    },
                    "status": {
                        "href": "(...)/user/vehicles/{id}/status"
                    }
                }
            },
                        {
                "id":,
                "vin": ,
                "brand": "Peugeot",
                "pictures": [(...)],
                "_links": {
                    "alerts": {
                        "href": "(...)/user/vehicles/{id}/alerts"
                    },
                    "trips": {
                        "href": "(...)/user/vehicles/{id}/trips"
                    },
                    "self": {
                        "href": "(...)/user/vehicles/{id}?locale=fr-FR"
                    },
                    "lastPosition": {
                        "href": "(...)/user/vehicles/{id}/lastPosition"
                    },
                    "telemetry": {
                        "href": "(...)/user/vehicles/{id}/telemetry"
                    },
                    "maintenance": {
                        "href": "(...)/user/vehicles/{id}/maintenance"
                    },
                    "status": {
                        "href": "(...)/user/vehicles/{id}/status"
                    }
                }
            }
        ]
    },
    "currentPage": 1,
    "totalPage": 1
}

Pagination #

Every collection in the API are browsable. Links provided in the response will let you navigate in the API endpoints like in a website.

First, collections comes with a pagination system. In your request you can add optional parameters:

• indexRange: specify where the collection begin and where it finishes.

  example: “indexRange=0-9” will retrieve only results 0 to 9.

• pageSize: is the maximum of results you want to return per page.

  example: “pageSize=15” will retrieve only 15 results per page.

As you can see in the previous example there is a _links object at the top of the response body. These links let you browse between pages in a collection. Look at this table for more info about this _links object:

Discovering Resources #

Resources in the API are using HAL for HATEOAS integration. It allows interaction inside the api resources. The purpose is to access and discover the API like you browse a website: navigating from one page to another. Links are named with the idea that you can understand easily what they are about.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "_links": { },
    "total": 32,
    "_embedded": {
        "Status": [
            {
              "lastPosition": {(...)},
              "preconditionning": {(...)},
              "energy": [(...)],
              "createdAt": "Mon Jun 03 08:35:36 GMT 2019",
              "autonomy": 290,
              "ignition": {(...)},
              "_links": {

                  },
                  "self": {
                      "href": "(...)status?indexRange=0-&pageSize=1&locale=fr-FR"
                  },
                  "vehicles": {
                      "href": "(...)/vehicles/{id}"
                    }
                }
            }
        ]
    },
  "currentPage": 1,
  "totalPage": 32
}

Let’s say you are browsing all the vehicles (example above). Look at the object status, inside each status object you can retrieve info about the vehicle it concerns, it includes last position, preconditioning, battery etc.

Furthermore, there is a _links object embedded in the status object. These links are relative to the object that they describe. They let you discover and browse the API. In the example below you can retrieve 3 links:

• "self": pointing to the actual resource.
• "vehicles": pointing to the vehicle this status is about.

Expected JSON Data #

Be careful, this API is very likely to have updates in the future, that’s why your application have to support evolution regarding the schema of exposed data.

In order to ensure the API backward compatibility with previous versions, we pledge to keep the same unit for each field in a JSON response body.

However, it’s possible that we choose to add a new field in a JSON response body. Your application should then handle dealing with unknown properties.

Furthermore, regarding the nature of this API, it could append that some fields are missing in the JSON response body. In this case, your application should be able to manage with the absence of the field and not cause an error.

Example

This is an example of an exposed resource data schema:

1
2
3
4
5
6
7
8
data:
type: object
description: Data model
properties:
    field1:
    type: string
    field2:
    type: number

And then here is a list of JSON data that your application should be able to handle:

1. All fields:

1
2
3
4
{
    "field1":"value1",
    "field2": 1
}

2. Missing fields:

1
2
3
{
    "field1":"value1"
}

3. Unknown fields:

1
2
3
4
{
    "field1":"value1",
    "field3": 2.5
}

See Also #

Connect

Stellantis End User API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) utilizes OAuth2 connection, follow this link for connection tutorial.

Monitors

Stellantis WEB API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) offer you Big Data features ! Look at Monitors.