API Introduction

Getting Started

This document describes the Application Programming Interface for OpenCarData.

The API consist of a set of function to store, retrieve and interpret car related data. Data is acquired from a car using an OBD interface and send to an Android device. The Android application wraps the raw OBD communication in XML and adds location information. The data is then send to the opencardata database and stored as a raw frame.

The server will then translate these raw frames in the background to create parsed frames. The parsed frames are then grouped to form trip information.

The server provides three types of data-access:

REST HTTP interface

The data on the server can be accessed using simple HTTP calls. These calls are implemented using the REST principles.

To test the calls, it is recommended that you use a command-line HTTP application such as CURL. You can also test the calls that use the GET method in a normal web browser. You should use the view source method of your browser to view the actual XML. For example, try view-source:http://opencardata.com/db/raw/48xznx?pagesize=10&page=2

All data, both send and received is in XML format. The most important XML documents are described below. Because the formats are currently very simple and self-explanatory, no XSD or DTD schemas are defined.

Raw data format

A raw frame describes the partial state of a car at given moment, and at a given location. In XML it looks like this: 


    <rawdata 
      lat="52.528102" 
	  lon="6.1027711" 
      time="1276704416423" 
      carid="60xzvn"
    >
      <data send="010F">010F 41 0F 43 </data>
      <data send="010D">010D 41 0D 56 </data>
      <data send="010C">010C 41 0C 1D 60 </data>
      <data send="010B">010B 41 0B 7C </data>
      <data send="03">03 43 00 </data>
      <data send="0110">0110 41 10 08 A3 </data>
    </rawdata>

The data elements in this document describe the exact communication sequence with the Engine Control Unit (ECU). Thus in this example, the Android application has send a 010F request which is a Mode 1 request for the Intake Air Temperature and the ECU's answer was 41 0F 43, which translates to 29°. The time attribute is a UNIX timestamp which will indeed translate to a hot summer a day at the given lat/lon location.

Raw frames can be added to the server using a HTTP PUT as described in the reference. This is the only method to add data to the database used by the client , since all other data is generated on the server.

Another example of a raw frame can be retrieved using the API call GET /db/raw/carid/time which retrieves a full RAW data frame from the database. To see what RAW frames are available on the server, you can use the GET /db/raw/carid and the GET /db/raw calls.

Trip data format

All incoming raw frames are interpreted by the server and stored in trip documents. In XML they look like this: 


	<trip 
		time="1277223710666" 
		endtime="1277224200555" 
		carid="15rlbd" 
		processtime="1277224200555" 
		startlocname="Zuna" 
		endlocname="Eversberg" 
		totaldistance="6470.081" 
		totalduration="489.889" 
		totalfuel="0.799901" 
		accuracy="0.817550"
	>
		<point 
			time="1277223710666" 
			lat="52.32206" 
			lon="6.506663" 
			duration="15.65" 
			distance="78.52" 
			fuel="0.0204138" 
			kmperl="3.84684"
		>
			<data time="1277223710666" type="start">
				<Speed>0</Speed>
				<MAF>0</MAF>
			</data>
			<data time="1277223714063">
				<IAT>23</IAT>
				<Speed>22</Speed>
				<RPM>1417</RPM>
				<MAP>100</MAP>
				<MAF>13.8</MAF>
				<Milage>4.81687820031</Milage>
			</data>
		</point>
		<point 
			time="1277223726316" 
			lat="52.322752" 
			lon="6.506894" 
			duration="24.143" 
			distance="141.319103" 
			fuel="0.0359420" 
			kmperl="3.93185"
		>
			<data time="1277223726316">
				<IAT>24</IAT>
				<Speed>24</Speed>
				<RPM>1522</RPM>
				<MAP>101</MAP>
				<MAF>15.75</MAF>
				<Milage>4.604184877179429</Milage>
			</data>
		</point>
	</trip>

The trip element contains attributes that are calculated for the entire trip, most of which are self-explanatory. For instance, this example was approximately 6.5km long and took a bit over 8 minutes. The accuracy attribute describes for which part of the trip actual measurements were used to calculate emission data, and which part was extrapolated. In this case, 82% of the data was collected, thus 18% was extrapolated

The actual data frames are direct translations of rawdata frames, but are wrapped in point elements. These point elements form a line segments. When two or more rawdata frames are measured on approximately the same location they are grouped in the same line segment.

Trip data can be retrieved using the GET /db/trip/carid/time call, and listed using the GET /db/trip/carid and the GET /db/trip calls.

Custom Queries

Besides the methods described above, you can retrieve any data by means of custom queries. These custom queries must be specified in XQuery

Using custom queries you can generate all kinds of data which is difficult to retrieve using the other API calls. The GET /db/query call can be used to issue a custom query.

You only have read access to the database when issuing a custom query

Function reference

Function: PUT /db/raw/carid/time

Stores a raw data frame in the database

This function is used by the client application to store a data frame. The data must be in the format described above.

The request should contain a "Content-type" header which should be "text/xml".

The XML document does not need to contain the carid or time attributes because these are already specified in the URL. Which data elements are included in the document is the choice of the client software. To send a simple raw frame with a single data element using curl try: 

    curl -X PUT -H 'Content-type: text/xml' \
	  -d '<rawdata lat="52.528102" lon="6.1027711"> \
		  <data send="010F">010F 41 0F 43 </data> \
		  </rawdata>' \
	  http://opencardata.com/db/raw/60xzvn/1276704416

Note that the carid should be unique and a corresponding record will be created if a new carid is specified

Function: GET /db/raw/carid/time

Retrieves a single raw data frame from the server

Reads a single raw data frame from the server. The returned XML document is unmodified from how it was stored, except that it will include carid and time attributes.

Examples:

Function: GET /db/raw/carid

Retrieves a list of raw frames for a specified car

Requests a list of raw data frames from the server. The list can be paged using the page and pagesize request parameters.

Only the attributes of the data frames are returned. To get the inner elements, you should issue a call to GET /db/raw/carid/time

Examples:

Function: GET /db/raw

Retrieves a list of raw frames

Requests a list of raw data frames from the server. The data is sorted by date, latest first. The list can be paged using the page and pagesize request parameters.

Only the attributes of the data frames are returned. To get the inner elements, you should issue a call to GET /db/raw/carid/time

Examples:

Function: GET /db/trip/carid/time

Retrieves a single trip from the server

Reads a complete trip from the server. If new points have just been added to the trip, the trip variables will be calculated on the fly. The format of the returned XML document is described earlier.

Examples:

Function: GET /db/trip/carid

Retrieves a list of trips for a specified car

Requests a list of trips from the server. The list is filtered for the specified carid and is sorted, latest first. The list can be paged using the page and pagesize request parameters.

Only the attributes of the data frames are returned. To get the inner elements, you should issue a call to GET /db/trip/carid/time

Examples:

Function: GET /db/trip

Retrieves a list of trips

Requests a list of trips from the server. The trips are sorted by date, latest first. The list can be paged using the page and pagesize request parameters.

Only the attributes of the data frames are returned. To get the inner elements, you should issue a call to GET /db/trip/carid/time

Examples:

Function: POST /db/car/carid

Stores car information

This method is currently under development and should not be used

Function: GET /db/car/carid

Retrieves general information of a vehicle

This function is used to retrieve additional vehicle information. Currently, only the expected emissions stored in the database. It is expected that detailed car information will be added in the future.

Examples:

Function: GET /db/car

Retrieves a list of cars

Requests a list of cars from the server. The list can be paged using the page and pagesize request parameters.

The list will contain the carids and the number of trips for each car.

Examples:

Function: GET /db/fillup/carid

Reads fillup information

Retrieves fillup frames for a car, amended with calibration information

Example:

Function: PUT /db/fillup/carid/time

Mark a fuel fillup

Send a frame to the server to notify that the fuel tank is filled. This will be used for calibration. The data should be an XML frame that looks like this: 


  <fillup 
    fuel="55"
    odometer="123115"
    fueltype="diesel"
  />

The amount of fuel supplied should be in litres. In the future a fuel-type field will be added

Function: GET /db/reprocess/carid/time

Recalculate trip data

Reinsert all raw frames in the database, while recalculated all relevant values. This should normally not be necessary as all variables are calculated automatically, but it can be useful if server side variables or algorithms have changed

The function will return the raw output of the reinsertion process

Function: GET /db/query

Issues a custom query

Sends a custom XQuery or XPath query to the server. The query should be passed as the query parameter. The data will be passed to the eXist database server and the results will be returned

The query is send with read-access only so no database changes can be made

Example: