API reference

IDDataLogger provides an API for integration with other systems and scripts. The API allows for simple querying of car status and previous charging sessions.

Authentication

IDDataLogger requires authentication to use its endpoints. Authentication is archived using a simple static access key (API key) that is sent in the query parameter 'key'. E.g.: hostname.tld/vwid/carStatus.php?key=xxx The API key is generated on first startup and displayed in the log. Additional api keys can be generated with ./start.sh --wizard.

Available endpoints

carStatus.php

Query parameters

parameter	possible values	default value	description	required
at	string accepted by the DateTime constructor of php. It is recommended to use @unixtimestamp where unixstimestamp is seconds since unix epoch.	now*	Gets the car status received at or the next one after the specified (UTC!) time.	no
attemptRefresh**	true/false	false	(PLANNED, NOT IMPLEMENTED) Instructs the backend to fetch	no

*Omit the parameter instead of sending now for performance reasons.

**Cannot be used in conjunction with the parameter at.

Returned data

JSON:

{
  "time":"YYYY-MM-DDTHH:MM:SS+00:00", # timestamp of data, always UTC (+00:00)
  "batterySOC":"41", # 0-100 percent
  "remainingRange":177, # km
  "remainingChargingTime":0, # mins
  "chargeState":"readyForCharging", # possible values: charging, chargePurposeReachedAndNotConservationCharging, readyForCharging, conservation, chargePurposeReachedAndConservation, error
  "chargePower":"0", # kW
  "chargeRateKMPH":"0", # km/h
  "targetSOC":"100", # 0-100 percent
  "plugConnectionState":"disconnected", # connected, disconnected
  "plugLockState":"unlocked", # invalid, locked, unlocked
  "remainClimatisationTime":0, # mins
  "hvacState":"off", # possible values: off, heating, cooling
  "hvacTargetTemp":"19.5", # °C
  "lastChargeStartTime":"YYYY-MM-DDTHH:MM:SS+00:00" # always UTC (+00:00)
}

carPicture.php

Returns a png picture of the car. This is usually the one fetched from VW, but technically it returns the contents the png file in data/carPic.png had at start time of the backend php process. (The png file is loaded into the database at every startup, if it does not exist it is fetched from VW.)

chargingSessions.php

Query parameters

parameter	possible values	default value	description	required
beginTime	seconds since unix epoch (unix timestamp) as an integer	0	filters all chargingSession with startTime before this timestamp	no
endTime	seconds since unix epoch (unix timestamp) as an integer	current timestamp	filters all chargingSessions with startTime after this timestamp	no

Returned data

JSON:

[
  {
    "id":5597, # random ID
    "startTime":"YYYY-MM-DDTHH:MM:SS+00:00", # plug in time, always UTC (+00:00)
    "endTime":"YYYY-MM-DDTHH:MM:SS+00:00", # plug out time, always UTC (+00:00)
    "chargeStartTime":"YYYY-MM-DDTHH:MM:SS+00:00", # started charging (chargeState switched to charging)
    "chargeEndTime":"YYYY-MM-DDTHH:MM:SS+00:00", # stopped charging (chargeState switched to readyForCharging)
    "duration":15664, # secs, charge session duration (chargeStart to chargeEnd)
    "avgChargePower":10.4, # kW
    "maxChargePower":11, # kW
    "minChargePower":8.5, # kW
    "chargeEnergy":162546, # kWs
    "rangeStart":81, # km, range remaining at startTime
    "rangeEnd":352, # km, range remaining at endTime
    "targetSOC":100, # 0-100 percent
    "socStart":17, # 0-100 percent
    "socEnd":100 # 0-100 percent
  }
  ,
  ...
]

idView/carGraphData.php

This endpoint returns certain values of carStatus over a time range. Used for the Graph in IDView. It is not described here since it is not part of the API. Please note that the existence, return values or parameters of this endpoint might change with any IDDataLogger update.