WEB API

for end-users

Overview - Standards

Info: Stellantis End User API for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available.

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:

METHOD ACTION
GET Retrieve resources
POST Create resources
PUT Change and/or replace resources or collections
DELETE Delete resources

HTTP Response #

Response Code Meaning
200 Request completed without any issues
400 Invalid request (ID, …)
403 The user don’t have access to this car. Usually an error with the vehicle ID.
404 Data not found. Can be that there is no data for this specific vehicle or a typo on the URL
429 Too Many Requests. The limit of requests have been exceed, see rate limit.
500 Internal server error. Sounds like there’s a problem on the server. Take it easy, we’re on it ;)

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": {
    (...)
  }
}
Property Type Description
_links object This property contain _links related to the current object. It can be _links to inside the current object or _links related to this object.
_links.self.href string URL of the current object
createdAt date Creation date: when the data was collected (UTC).
updatedAt date Last update date
_embedded object This property contains commonly related objects to the current object. It can be empty.

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:

Property Type Description
_links object This property contain _links related to the current object. You can use these _links in your application to store:
_links.self.href string URL of the current position in the array
_links.first.href string URL for the first page of the array. Optional
_links.next.href string URL for the next page of the array. Optional
_links.prev.href string URL for the previous page of the array. Optional
_links.last.href string URL for the last page of the array. Optional
total integer Total number of elements in the array. Depends on the filters applied to the search.
_embedded object This property contains commonly related objects to the current 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.