Documentation

API for the connected vehicle

Welcome to the PSA Group API !

In this page you will find all the information needed to get started building applications and services with the PSA Group Connected Car API.

Should you run into any technical issues, please contact us by emailing connectedcar@mpsa.com.

First steps

You don't need a Peugeot Citroën or DS car to create applications. You have not, either, need a dongle. To test an API operation, put random values for VIN and CONTRACT and we will replace these parameters on the fly, by one of our test cars. These are real cars, driven daily.

Once you want to launch your app or service in production, just send us a quick email.

Create an account

The first step is to register on the platform : https://developer.psa-peugeot-citroen.com/user/register

Create an application.

Once logged in, you need to create a new app : https://developer.psa-peugeot-citroen.com/application/new

Subscribe to a plan.

Then choose one API Product : https://developer.psa-peugeot-citroen.com/product click on the Subcribe button and select your app.

You are now able to perform some API calls !

Rest API

The PSA Group API allows your application to request data regarding three main domains:

Telemetry

These APIs lets your application request data from the car: average speed, location, instantaneous consumption, engine speed, etc.

Maintenance / Alerting

These APIs lets your application request data from the various events or notifications that can be detected by the car: time before maintenance, fired alerts, etc.

Correlation

These APIs lets your application evaluate your driving style with others.

Examples of API call

Simple call

In this example we will request the last trip.

Example Request:

curl -X GET -H "Cache-Control: no-cache" "https://api.mpsa.com/api/dev/1.0/trip/last/FOO?contract=BAR&limit=1&unit=1&client_id=INSERT_YOUR_CLIENT_ID"

Example Response:

{
  "totalNumberTrips": 356,
  "trips": [
    {
      "tripId": 101131,
      "dateTripBegin": "20151116121747",
      "dateTripEnd": "20151116121830",
      "tripDuration": 43,
      "dateUpdate": "20151116121750",
      "avgFuelConsumption": 2.63,
      "deltaFuelLevel": 0,
      "tripMileage": 0,
      "totMileage": 3119.41,
      "avgSpeed": 1,
      "engineSpeed": 821,
      "engineOilTemp": 0,
      "fuelPrice": 0,
      "tripCost": 0,
      "referenceTrip": 0,
      "CO2Emission": 0,
      "ecoDriving": 0,
      "refueling": 0,
      "modePrivacy": 0,
      "refuelingCost": 0,
      "siphoning": 0,
      "siphoningCost": 0,
      "fuelTankLevel": 72,
      "tripFuelConsumption": 0,
      "geoLocalisation": {},
      "vin": "VF700000000000000",
      "contract": "ABCDEF12345"
    }
  ]
}

Dealing with seconds

In this call we will request the last position of e vehicle at specific seconds.

Example Request:

curl -X GET -H "Cache-Control: no-cache"  "https://api.mpsa.com/api/dev/1.0/place/lastposition/FOO?contract=BAR&listsecond=1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20&near=1&client_id=INSERT_YOUR_CLIENT_ID"

Result:

{
  "latitude": {
    "6": "48.94876",
    "12": "48.94876",
    "18": "48.94876",
    "24": "48.94876"
  },
  "longitude": {
    "6": "2.05046",
    "12": "2.05046",
    "18": "2.05046",
    "24": "2.05046"
  },
  "altitude": {
    "6": "19",
    "12": "19",
    "18": "19",
    "24": "19"
  },
  "nbsat": {
    "30": 3
  },
  "source": {
    "6": "2",
    "12": "2",
    "18": "2",
    "24": "2"
  },
  "vin": "VF700000000000000",
  "lastUpdate": "20151117080446",
  "contract": "ABCDEF12345"
}

How is the data collected?

The vehicles transmit, every minute, by a private channel, the data of the vehicle. All this information is then processed by the PSA Group's servers in our datacenters. The access to the data is then filtered by APIs security scheme.

The data is collected in 2 messages. The information is sampled at a specific rate depending on the type of message.

The event message is received:

  • At startup
  • At shutdown
  • On a crash

The periodic message is received every minute.

Detailed specifications

Introduction

This part gives you an outline of the different APIs available for your application.

It is important to note that this API is in constant evolution.

The car send data by chunk of 1 min. In this frame, informations are collected at a specific rate. By default, the 41st second is the second of the extraction. Beware that depending on the sampling rate of specific information, you may not have any data.

Here you have the main parameters for a request. Each operation can be called for a specific car (VIN, contract) or a list of cars (listvin, listcontract).

Name of the parameter Type Description
VIN String Vehicle Number Identification, or VIN, is a single alphanumeric code which is given to each motor vehicle since 1954.
contract String The contract associated with the vehicle
listvin/listcontract ParamsList {'listcontract':[''], 'listvin':['']} You can pass a list of VINand CONTRACT by using the POST HTTP verb. In this case the list must be provided in the payload of the request. Ex: {'listvin':['vin1', 'vin2'], 'listcontract':['contract1', 'contract2']}
codesecure String access code
local String The locale. Ex: fr_FR for French
brand String The brand. Ex: P = Peugeot, C = Citroën or DS
active String Used to seek an active alarm. 0 = inactive, 1 = active.
listsecond String 1,2,3,4,5,…., 60. It is the list of the requested seconds separated by commas [1,60].
day String yyyyMMdd. Ex 20150215 (February 2nd, 2015)
fromday String yyyyMMdd. Ex: 20150215. It is the lower limit.
today String yyyyMMdd. Ex: 20150215 (February 15th, 2015). It is the upper limit.
frommonth String yyyyMM. Ex: 201502 (February 2015). It is the lower limit.
tomonth String yyyyMM. Ex: 201502 (February 2015). It is the upper limit.
from String yyyyMMddHHmm. Ex: 201502151155 (February 15th, 2015 at 11:55 min). It is the lower limit.
to String yyyyMMddHHmm, represents the date. Ex: 201502151155 (February 15th, 2015 at 11:55 min). It is the upper limit.
near String Only for the geolocation service. The position of the car is sampled at 0.17 Hz (every 10s). With near set to 1 , if you request a second where there is no data the API will give you the next non null value.

Maintenance

This service returns the various elements related to the preventive maintenance and alerts

You can get alerts and maintenance information by calling:

  • GET:/1.0/maintenance/{VIN} for maintenance.
  • GET:/1.0/alerte/{VIN} for alerts.
Name of the parameter Type Description
totMileage integer Total mileage (in km).
indDayBeforeMaint String Flag for maintenance (in days) 0 = Normal (+) 1 = Maintenance out-of-date (-) 2 or 3 = Invalid
indMileageBeforeMaint String Flag for maintenance (in mileage) 0 = Normal (+) 1 = Maintenance out-of-date (-) 2 or 3 = Invalid
dayBeforeMaint integer Days before maintenance. Passes into negative when exceeded.
mileageBeforeMaint integer Mileage before maintenance. Passes into negative when exceeded.
fuelLevel integer Amount of fuel as percentage of total capacity
fuelTankAlerte integer Low level fuel alert. 0 = Off 1 = On 2 or 3 = Invalid
residualAutonomy integer Mileage autonomy.
fuelTotalConsumption integer Fuel total intake since initial entry into service (in liters).
fuelTankCapacity integer Fuel tank capacity.
instFuelConsumption (I) integer Instantaneous fuel consumption in L/100 km.

For alerts:

Name of the parameter Type Description
idAlert String Id of the alert. 004 = excessive engine temp 005 = insufficient coolant level. 023 = parking brake/failing system antirecul…
dateAlertBegin String Start date of alert
dateAlertEnd String End date of alert
alertState integer Status 0 = Inactive 1 = Active.
alert String Short explaination of the alert
category String Category of the alert
advise String Advise given to the driver

Trip

Provide information on trips.

  • GET:/1.0/trip/id/{VIN}/{tripid} provide a single trip's detail
  • GET:/1.0/trip/period/{VIN} provide detail of all trips included in the period
  • GET:/1.0/get/referencetrip/{VIN} provide the reference trip's detail.
  • GET:/1.0/trip/last/{VIN} provide the N last trip's details.
  • GET:/1.0/get/reference/fueprice/{VIN} Get the fuel price of the reference trip
  • PUT:/1.0/trip/update/fuelprice/{VIN}/{tripid} set the fuel price for a trip
  • PUT:/1.0/trip/update/reference/fuelprice/{VIN} set the fuel price for the reference trip
  • PUT:/1.0/trip/update/referencetrip/{VIN} set the reference trip

The various attributes which one can find in the answer of the call to the various related services to the module way are:

Name of the parameter Type Description
engineSpeed BigDecimal Engine speed (RPM).
totMileage BigDecimal Total mileage since initial service
tripId integer Identifier of the trip
refueling integer Refueling flag 0 = refueling 1 = no refueling
siphoning integer Siphoning flag during the trip. 0 = siphoning 1 = not siphoning during the trip
ecoDriving BigDecimal ecodriving evaluation of the trip
dateTripBegin String (yyyyMMddHHmmss) Begin date for the trip
dateTripEnd String (yyyyMMddHHmmss) End date for the trip
avgFuelConsumption BigDecimal Average fuel consumption.
tripFuelConsumption BigDecimal Fuel consumption during the way.
tripDuration integer Trip duration
deltaFuelLevel BigDecimal percentage variation of fuel consumption during the trip.
tripMileage BigDecimal Trip mileage
tripCost BigDecimal Trip cost
engineOilTemp BigDecimal Engine oil temp (in C°)
fuelPrice BigDecimal Fuel price set by the user
avgSpeed BigDecimal Average speed for the trip
referenceTrip integer Reference flag 0 = this trip is reference 1 = this trip is not a reference
cO2Emission BigDecimal Quantity of CO2 emission (estimated).
refuelingCost BigDecimal Refueling cost
siphoningCost BigDecimal Siphoning cost
fuelTankLevel BigDecimal Fuel tank level in percent.

Ecodriving

Provide an evaluation of your driving style. You get a mark from 1 to 10 compared with the other drivers of its category (Silhouette Conveys, driving, limps…).

These marks are based on a social algorithm. It can vary if the population improves overall more quickly than the driver. Beware; it is necessary that the trip mileage is at least 2 kms to get an evaluation.

  • GET:/1.0/ecodriving/evaluation/get/{VIN} provide an ecodriving evaluation of all the trips of a vehicle.
  • GET:/1.0/ecodriving/evaluation/daytrips/{VIN} provide an ecodriving evaluation of all the trips of a vehicle for a specific day yyyyMMdd.
  • GET:/1.0/ecodriving/evaluation/pertrip/{VIN}/{tripid} provide an ecodriving evaluation for a specific trip
  • GET:/1.0/ecodriving/evaluation/lasttrip/{VIN} provide an ecodriving evaluation for the last trip
  • GET:/1.0/ecodriving/evaluation/trip/day/{VIN} provide an ecodriving evaluation of all the trips in the time interval indicated [fromday, today] (format:yyyyMMdd).
  • GET:/1.0/ecodriving/evaluation/trip/month/{VIN} provide an ecodriving evaluation of all the trips in the month
Name of the parameter Type Description
duration integer Trip duration in second.
roadProfile BigDecimal Total mark based on the notes balanced by:consumption + Slope + ColdTrip.
tripId integer Trip id
tripDuration integer Trip duration in second.
dateAggr String (yyyyMMdd-day/yyyyMM-month) Date of the evaluation
drivingMark BigDecimal Driving mark DriveAttitude (60%) RoadProfile (40%)
drivingAttitude BigDecimal Driving attitude Acceleration Braking
acceleration BigDecimal Acceleration mark
braking BigDecimal Braking mark
coldTrips BigDecimal based on the percentage of time spent in trips when the temperature of engine oil is bigger than 85 C°.
engineSpeed BigDecimal RPM mark
slope BigDecimal Evaluation of the slope of you trip. Beware ; a mark of 5 out of 10 match with somebody who rolls flat, a mark of 3 match with somebody who makes more way up than the other drivers, 8 for someone which takes more way down.
stopAndStart BigDecimal use of the system stop and start mark
speed BigDecimal Speed mark
xxxxLabel EcodrivingLabel This is the recommendation made by the system

Running/Light

Provide information while the vehicle is running.

  • GET:/1.0/data/running/{VIN} returns information of the last rolling of the vehicle.
  • GET:/1.0/running/data/lightstatus/{VIN} returns last information of lighting of the vehicle.

The various attributes which one can find in the answer of the call to the service running are:

Name of the parameter Type Description
engineSpeed Map [String, BigDecimal] Engine speed (RPM)
tempOilEng BigDecimal Temperature of the engine oil in C°
modeBV Map [String, BigDecimal] Gear mode. 0 = Car 1 = Not used 2 = Car + Sport 3 = Not used 4 = Sequential 5 = Sequential + Sport 6 = Car + Snow 7 = Not used 8 = Invalid
fuelLevel String Fuel level in %
instFuelConsumption Map [String, BigDecimal] Fuel consumption in Liter (L/100 km)
gmpState BigDecimal Engine state 0 = Engine not running 1 = Starting 2 = Engine running 3 = Engine stopped in stop phase 4 to 7 = Invalid

The various attributes which one can find in the answer of the call to the service running are:

Name of the parameter Type Description
fogFront Map [String, int] Statutes of front fog. 0 = Fog lights off 1 = Fog lights on 2 or 3 = Invalid
fogRear Map [String, int] Statutes of back fog. 0 = Fog lights off 1 = Fog lights on 2 or 3 = Invalid
turnRight Map [String, int] Statutes of the right indicators. 0 = Right indicator off 1 = Right indicator on 2 or 3 = Invalid
turnLeft Map [String, int] Statutes of the indicators left. 0 = Left indicator off 1 = Left indicator on 2 to 3 = Invalid
brakeLight Map [String, int] Indicator of fires stop (inactive for the moment)

Crash

This module returns the elements related to the state of a vehicle.

By calling GET:/1.0/crash/get/{VIN} you will get the detection of the last crash and its intensity.Back, Front, Side;Raised, Average, weak and reparable.

Name of the parameter Type Description
flipVeh Map [String, int] Detection of a flip of the vehicle. 0 = the vehicle has not made a flip; 1 = the vehicle has made a flip; 2 or 3 = Invalid
avgRearCrashInfo Map [String, int] Rear medium crash detection 1 = Crash not detected; 2 = Crash detected; 3, 4 = Invalid
lowRearCrashInfo Map [String, int] Read low crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
repairRearCrashInfo Map [String, int] Reparable rear crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, `4 = Invalid
highFrontCrashInfo Map [String, int] Front high crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
avgFrontCrashInfoN1 Map [String, int] Front medium crash detection 1 = Crash not detected; 2 = Crash detected; 3, 4 = Invalid
avgFrontCrashInfoN2 Map [String, int] Front medium crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
lowFrontCrashInfo Map [String, int] Front low crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
repairFrontCrashInfo Map [String, int] Reparable front crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
pedestCrashInfo1_60 Map [String, int] Pedestrian crash detected in the 20 first sec and restored to the 60st sec 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
pedestCrashInfo2_60 Map [String, int] Pedestrian crash detected in the second 20 sec and restored to the 60st sec 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
pedestCrashInfo3_60 Map [String, int] Pedestrian crash detected in the last 20 sec and restored to the 60st sec 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
pedestCrashInfo1_41 Map [String, int] Pedestrian crash detected in the 20 first sec and restored to the 41st sec1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid Only detected in the event message
highLatCrashInfo Map [String, int] High lateral crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
avgLatCrashInfo Map [String, int] Medium lateral crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
lowLatCrashInfo Map [String, int] Low lateral crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
repairLatCrashInfo Map [String, int] Reparable lateral crash detection 1 = Crash not detected; 2 = Crash landing detected; 3, 4 = Invalid
totMileage Map [String, int] total mileage of the vehicle

Safety

This module returns information regarding safety and driving assistance (ADAS)

  • GET:/1.0/safety/drivingassistance/{VIN}
  • GET:/1.0/safety/{VIN}
Name of the parameter Type Description
autoECall integer Status of the emergency call. 0 = Airbag calculator unable to detect a shock; 1 = No request to send an auto Ecall; 2 = Request to send an auto Ecall; 3 = Not used; 4 to 7 = Invalid
afil Map [String, int] Alarm for involuntary line crossing. 0 = off; 1 = on fixed; 2 = flashing fault; 3 = flashing warning; 4 to 7 = Invalid
adsrl Map [String, int] Status of speed limit system. 0 = All functions OFF 1 = RVV ON 2 = LVV ON 3 = ACC ON 4 to 7 = Invalid
respectTimeIntVeh Map [String, int] Inter vehicle time respect. 0 = Not selected; 1 = Selected; 2 = Selected but unavailable; 3 = Invalid
survBlindSpot Map [String, int] Blind spots monitoring. 0 = Inactive; 1 = Active; 2 = Value not used; 3 = Value not used; 4 = Inhibited; 5 = Value not used; 6 = Invalid; 7 = Fault
speedInfoPanel Map [String, int] Last seen speed limitation on the road (in kilometers/hour)
rearSoundParkAssist Map [String, int] Rear sound park assist sound status. 0 = Not defined; 1 = Fault; 2 = Driver inhibition; 3 = Trailer inhibition; 4 = Active; 5 = Wait; 6 = Out of service; 7 = Not defined; 8 to 9 = Invalid
frontSoundParkAssist Map [String, int] Front sound park assist sound status. 0 = Not defined; 1 = Fault; 2 = Driver inhibition; 3 = Trailer inhibition; 4 = Active; 5 = Wait; 6 = Out of service; 7 = Not defined; 8 to 9 = Invalid
laneKeepAssistLeft Map [String, int] Left lane keep assist status 0 = Not selected; 1 = Not authorized; 2 = Authorized; 3 = Correction in progress; 4 to 7 = Invalid
laneKeepAssistRight Map [String, int] Right lane keep assist status 0 = Not selected; 1 = Not authorized; 2 = Authorized; 3 = Correction in progress; 4 to 7 = Invalid
infoBeltSecurity Map [String, int] Seat belt status (for all passengers). 0 = Normal; 1 = Omission; 2 or 3 = Invalid
adEmergencyBrakeSystem Map [String, int] Emergency brake system status 0 = off; 1 = on fixed; 2 = on flashing; 3 = value not used
ABS Map [String, int] ABS status. 0 = Not in regulation; 1 = In regulation; 2 or 3 = Invalid
esp Map [String, int] ESP status. 0 = Inactive; 1 = Active; 2or 3 = Invalid
adAsrvvi Map [String, int] Advanced speed Regulator Assistance 0 = No best fit RVVi; 1 = Best fit RVVi in progress; 2 = Best fit RVVi Max; 3 = Best fit RVVi V MIN; 4 = Best fit RVVi speed deactivated; 5 = RVVi auto deactivated; 6 = Overflow RVVi speed consign; 7 = Lack of visibility radar; 8 = Learning radar; 9 = RVVI deactivated; 10 = RVVI limit setting; 11 = Not used; 12 = Not used; 13 = Not used; 14 = Not used; 15= Not used; 16 to 31 = Invalid

|

Place

Module for geolocation of the vehicle.

  • GET:/1.0/place/lastposition/{VIN} last position of the vehicle.
  • GET:/1.0/place/positions/trip/{VIN} path of a trip
Name of the parameter Type Description
altitude Map [String, String] Altitude
latitude Map [String, String] Latitude
longitude Map [String, String] Longitude
nbsat Map [String, BigDecimal] Scale of quality of the GPS signal. 1 = 1 (Low Signal) 2 = 2 3 = 3 4 = 4 5 = 5 6 = 6 7 = 7 8 = 8 9 = 9 (Higher signal)
source Map [String, String] GPS source. 0 = Invalid 1 = GPS 2 = GPS estimated 3 = Invalid

Environment

Information from outside.

  • GET:/1.0/environment/get/{VIN} .
  • POST:/1.0/environment/list
Name of the parameter Type Description
infoDayAndNight Map [String, int] Day/night detection 0 = Day 1 = Night 2 or 3 = Invalid
exteriorTemp Map [String, BigDecimal] Outside temperaturein C°