API

Specifications

Overview - API Concepts

Edit Jira

This API is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint.

This REST API returns type MIME: application/hal+json, GeoJson for location and RFC3339 for time format.

This API is available for Stellantis.

HTTP Response #

Response Code Meaning
200 The request has succeeded and the resource data has been sent.
202 The request has been accepted for processing, but not yet acted upon. An id of processing is returned.
204 The request has been accepted and there is no additional content
400 Request cannot be processed due to invalid query parameter value of body content (for POST/PUT verbs)
401 Unauthorized request due to lack of valid authentication credentials.
403 Unauthorized request due to insufficient credentials to grant access.
404 Target resource not found.
500 Unexpected condition that prevented from fulfilling the request.
501 Internal server error.

Error & Rate Limit: See this page for more information about errors & rate limit.

Single Object #

When you call for a resource with an {id} in the endpoint, the response will be a single object. All these endpoints respond with 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 contains _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 endpoint with a plural noun in the path (and not {id} tag), the response is an array of objects. All these endpoints respond with 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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207

{
  "_links": {
    "self": {
      "href": "string",
      "templated": true,
      "type": "string",
      "deprecation": "string",
      "name": "string",
      "title": "string",
      "profile": "string",
      "hreflang": "string"
    },
    "first": {
      "href": "string",
      "templated": true,
      "type": "string",
      "deprecation": "string",
      "name": "string",
      "title": "string",
      "profile": "string",
      "hreflang": "string"
    },
    "next": {
      "href": "string",
      "templated": true,
      "type": "string",
      "deprecation": "string",
      "name": "string",
      "title": "string",
      "profile": "string",
      "hreflang": "string"
    },
    "prev": {
      "href": "string",
      "templated": true,
      "type": "string",
      "deprecation": "string",
      "name": "string",
      "title": "string",
      "profile": "string",
      "hreflang": "string"
    },
    "last": {
      "href": "string",
      "templated": true,
      "type": "string",
      "deprecation": "string",
      "name": "string",
      "title": "string",
      "profile": "string",
      "hreflang": "string"
    }
  },
  "total": 0,
  "totalPage": 0,
  "currentPage": 0,
  "_embedded": {
    "vehicles": [
      {
        "_links": {
          "self": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "lastTelemetries": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "telemetries": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "collisions": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "trips": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "maintenance": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "alarms": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "alerts": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "remotes": {
            "href": "string",
            "templated": true,
            "type": "string",
            "deprecation": "string",
            "name": "string",
            "title": "string",
            "profile": "string",
            "hreflang": "string"
          },
          "groups": [
            {
              "href": "string",
              "templated": true,
              "type": "string",
              "deprecation": "string",
              "name": "string",
              "title": "string",
              "profile": "string",
              "hreflang": "string"
            }
          ]
        },
        "vin": "string",
        "brandCode": "string",
        "familyCode": "string",
        "motorization": "Electric",
        "fuelType": "Gas",
        "_embedded": {
          "extension": {
            "devices": {
              "Device": [
                {
                  "type": "pnc",
                  "description": "string",
                  "additionalproperties": {
                    "key": "string",
                    "value": "string"
                  }
                }
              ]
            },
            "callCenterNumbers": [
              {
                "callType": "ECALL",
                "phoneNumber": "string"
              }
            ],
            "settings": {
              "pairing": {
                "url": "string",
                "password": "string"
              },
              "workflow": {
                "vehicleState": "Unpaired",
                "passworddStatus": "Generated",
                "workflowState": "InProgress",
                "certificateStatus": "Installed"
              }
            }
          }
        }
      }
    ]
  }
}

Pagination #

All collections in this API are browsable. Links provided in response allow navigating in the API endpoints like on a website.

First, collections come with a pagination system. In the request you can add these optional parameters:

  • indexRange: allows specifying which elements of the array need to be returned, by requesting a range of elements.
    Example: indexRange=0-9 will retrieve only elements 0 to 9 of this collection.

  • pageSize: is the maximum of results you want to receive per page.
    Example: pageSize=15 will retrieve only 15 results per page. Use the _links objects to navigate between pages.

As seen in the previous example, there is an _links object in the response body. These links allow navigating in the pages of this collection.

Property Type Description
_links.self.href string URL of the current page in the array.
_links.first.href string URL of the first page of the array. Optional
_links.next.href string URL of the next page of the array. Optional
_links.prev.href string URL of the previous page of the array. Optional
_links.last.href string URL of the last page of the array. Optional
total integer Total number of elements in the array.
_embedded object This property contains the response of this endpoint.

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 for

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

{
  "_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
}

The main resource is stored in the object_embedded.Status.

Then, inside this main object, there is a _links property relative to this Status object. It allows discovering resources and navigate in the API. In the example below, you can retrieve the following links:

  • "self": pointing to itself.
  • "vehicles": pointing to the vehicle resource is about.

Expected JSON Data #

Be careful, this API is very likely to have updates in the future, that’s why your application has 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
}