Charts

The Charts module is used to view charts and graphs containing data from the other core modules. Each supported type is prefixed by it's parent module below, and will honour any filters passed that are supported by the parent.

Charts can be made public for embedding into websites (as seen on the example charts page), or can be kept private to the user.

 

Request Specifics

As with any other module, any variables relevant to the request should be POST'd as JSON within a variable called data.

Currently supported are

  • smoothing - Boolean - Should values be normalised against a running average?
  • deviation - INT - What percentage deviation is permitted before the value is normalised (to the top of the range)
  • redirect - Boolean - If set to true, the API will not return JSON and will simply 302 to the generated chart
  • makePublic - Boolean - Make the chart public (default false)
  • chart->showLegend - Boolean - Show chart legend?
  • chart->showValues - Boolean - Include the exact values within the linechart
  • chart->useCurve - Boolean - Use a cubic curve to link the points
  • chart->showMarkers - Boolean - Include a marker for each datapoint
  • chart->Height - Height in pixels for the resulting chart
  • chart->Width - Width in pixels for the resulting charts
  • chart->XScale - How often should a value on the X axis be marked?
  • chart->Title - String - Title to use for the chart. Send with an empty value to disable the title.

Note: If specified, width and height must be specified together. If only one is specified they will be ignored. Redirect can also be appended as part of the request URI

Example

  {
"smoothing":false,
"deviation":60,
"redirect":true,
"makePublic": true,
"chart":{
"showLegend":true,
"showValues":true,
"useCurve": false,
"showMarkers": true,
"Height":460,
"Width": 800,
"XScale": 3
 }
}

The example above disables value normalisation and redirects the browser to the chart. Every 3rd value is marked on the X Axis.

 

Response

The API responses are in line with the rest of the API, unless you elect otherwise in your request you will receive JSON.

Within response will be ChartURL - this contains the full URL to use to view the chart.

Example

  {
"timestamp":1378240663,
"response":{
"cacheStatus":"MISS",
"ChartURL":"http:\/\/vehiclefueltracker.co.uk\/chartCache\/F-A123-DAL-ad2a34d12119fee25e49bee5d476c3c52a29c81b.png"
},
"errors":null,
"error":0
}

 

Charting Engines

The Charts module supports two main engines - pChart and Google Charts. The former generates a PNG image containing the requested chart, whilst the latter generates an interactive chart embedded into a webpage.

pChart

pChart is the default engine as it suits a wider range of applications, Google charts do not work well on some mobiles and are not well suited for any application that may lack an internet connection (i.e.) they can't easily be cached locally.
Therefore, to use pChart, you simply need to place requests exactly as described in this documentation

Google Charts

The Google Charts API can generate some attractive looking charts, which are well suited to being embedded within a webpage. In order to use the GoogleChart engine, place requests exactly as specified in this document, but add an additional segment to the end of the request URL - google.

So to request an economy chart we might use

/chart/economy/1/google

 

Fuel - Vehicle Economy

To generate a linegraph containing a single vehicle's average monthly economy

/chart/economy/{Vehicle Identifier}

The vehicle ID is preferred, but the registration can be used.

 

Fuel - Vehicle Average Price per Litre

To generate a chart containing the average price per litre throughout the recorded lifetime of a vehicle

/chart/fuelprice/{Vehicle Identifier}

 

Fuel - Historic Average Price per Litre

To generate a chart containing the average price per litre throughout the recorded history of a driver (based on all vehicles assigned to them)

/chart/allfuelprices

The driver used will be the one associated with the API Key used to authenticate against the system.

 

Fuel - Monthly Fuel Cost

To generate a chart showing a vehicles Monthly fuel cost,

/chart/fuelcost/{Vehicle Identifier}

 

Fuel - Monthly Fuel Cost Per Mile

To generate a chart showing the monthly fuel cost per mile

/chart/monthlyfuelcpm/{Vehicle Identifier}

 

Fuel - Monthly Mileage

To generate a chart showing a vehicles monthly mileage (based on fuel records)

/chart/monthlymileage/{Vehicle Identifier}

 

Servicing - Monthly Maintenance Cost

To generate a chart displaying the total monthly maintenance cost /chart/monthlyservicecost/{Vehicle Identifier}

 

Servicing - Monthly Maintenance Costs

To generate a chart displaying a breakdown of Monthly maintenance costs between fault and non-fault repair /chart/monthlyservicebreakdown/{Vehicle Identifier}

 

Journeys - Journey Route

The charting API can also generate a Google Maps call with a specific journey's route pre-plotted. To generate, use

/chart/journeyroute/{Vehicle Identifier}/{Journey Identifier}/{Segment Identifier (optional)}

 

Journeys - Journey Speed Profie

Generates a chart mapping the speed travelled during the specified journey.

/chart/journeyspeed/{Vehicle Identifier}/{Journey Identifier}/{Segment Identifier (optional)}