API, Blog, PHP, WordPress Shortcode

Australian Road Safety API

One of the projects were currently working on enjoys a working title of the Australian Security Journal. Located at police.com.au , the project is one that we're using as a security shopfront and magazine-style publication. We're of the opinion that any marketing company worth its weight will continue to have a significant portfolio of their own products and websites to demonstrate various concepts and expertise... and the Journal is just one of them. We plan on including as much dynamic information and crime data as possible, and one of those features - however morbid - is a count of deaths resulting from road accidents. This article introduces some of the basic features of the 'Road Safety' API we've built to support research necessary for article content, and data for display on the website.

Data sources described below are checked daily for updates. The API data returned is always sourcing the most up-to-date information.

Fatalities This Year

Data is sourced from The Bureau of Infrastructure, Transport and Regional Economics (BITRE) ... although they only update their database once per month. Heavy vehicle flags are only updated each quarter, and are only current to within two months. The date of crash has been removed, although the year, month and day of week are retained. So, generally speaking, real-time data is unreliable and incomplete but historical data, however incomplete, might be considered to be accurate.

The basic endpoint returns general statistics as follows:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => The Bureau of Infrastructure, Transport and Regional Economics (BITRE)

[data] => Array

(

[last_month_count] => 96

[last_year_count] => 1132

[this_month_last_year] => 88

[this_year_so_far] => 96

[valid] => Array

(

[year] => 2018

[month] => January

)

Using the shortcode of [bmfatalities] we return the this_year_so_far count as [bmfatalities]. The valid array contains the validity of the data returned (again, the data isn't overly accurate, so the 'real-time' count is usually around a month old).

To show the count as I've demonstrated above, the following shortcode was used:

<?php

Australian Road Safety API

https://www.beliefmedia.com.au/road-safety-api

function beliefmedia_police_fatalities($atts) {

$atts = shortcode_atts(array(

'type' => 'summary',

'apikey' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',

'p' => 0,

'cache' => 3600 * 24 * 5

), $atts);

$transient = 'bmpfa_' . md5(serialize($atts));

$cachedposts = get_transient($transient);

if ($cachedposts !== false) {

return $cachedposts;

} else {

/* Get Police Stats */

$data = @file_get_contents('http://api.beliefmedia.com/police/police.php?type=' . $atts['type'] . '&apikey=' . $atts['apikey']);

if ($data === false) return 'N/A';

$data = json_decode($data, true);

if ( ($data === false) || (empty($data)) || ($data['code'] != '200') ) return 'N/A';

/* Data */

$data = $data['data'];

$return = $data['this_year_so_far'];

if ($p) $return = '' . $return . '';

/* Set transient chart data */

set_transient($transient, $return, $atts['cache']);

return $return;

}

add_shortcode('bmfatalities', 'beliefmedia_police_fatalities');

Copy and paste the WordPress function into your theme's functions.php file or, if you sensibly have one installed, your custom functions plugin.

If you require shortcode to work in a sidebar widget, you'll have to enable the functionality with a filter. If you're using our custom functions plugin, you'll have that feature enabled by default.

Historical Data

We can return historical data dating back to 1989 with the endpoint of http://api.beliefmedia.com/police/police.php?type=year&apikey=xxxx.

Array

(

[code] => 200

[status] => 200

[message] => OK

[current_page] => 1

[total_page] => 1

[results] => 30

[source] => The Bureau of Infrastructure, Transport and Regional Economics (BITRE) | Australian Bureau of Statistics

[data] => Array

(

[1989] => Array

(

[fatal_count] => 2800

[year] => 1989

[population] => 16814416

[fatalities_per_1000] => 16.65

[fatal_crashes] => 2407

)

[------ SNIP ------]

[2016] => Array

(

[fatal_count] => 1293

[year] => 2016

[population] => 24210809

[fatalities_per_1000] => 5.34

[fatal_crashes] => 1199

)

[2017] => Array

(

[fatal_count] => 1227

[year] => 2017

[population] => 24525809

[fatalities_per_1000] => 5

[fatal_crashes] => 1132

)

[2018] => Array

(

[fatal_count] => 103

[year] => 2018

[population] => 24840809

[fatalities_per_1000] => NA

[fatal_crashes] => 96

)

Population data is sourced and updated as necessary from the Australian Bureau of Statistics. When full year statistics aren't available we use predictive data based on expected population growth. The fatalities_per_1000 value is only available when a full year of data is returned.

Date returned is updated only when required - which isn't very often. For this reason it's worth caching the data with Simple Cache and checking our API only occasionally for updates.

Querying Data

Data can be queried based upon any of the fields available in the source data. While queries may be grouped in a complex manner, the most basic query is described below.

month_start: The full month.
month_end: The full month.
year_start: The lowest year value.
year_end: The higher year value.
state: Query a specific state data.
crash_type:

1- Single vehicle
2 - Multiple vehicles
3 - Pedestrian

bus: Use bus=yes to query only accidents involving buses.
rigid: Indicates involvement of a heavy rigid truck in the crash. Use rigid=yes.
articulate: Indicates involvement of an articulated truck in the crash.
speed_start: The lowest speed value.
speed_end: The higher speed value.
road_user:

1- Driver
2 - Passenger
3 - Pedestrian
4 - Motorcycle rider
5 - Motorcycle pillion passenger
6 - Bicyclist (includes pillion passengers)

gender: To split results, use the following:

1- Male
2 - Female
3 - Unknown

age_start: Lower age limit.
age_end: Upper age limit.

The type attribute should be set to ?type=custom (if not provided we'll return only the basic statistical data). Additional parameters may be used to group results by any attribute, such as state, and this information is available within the client portal. Because of the large datasets returned, most results are paginated.

Considerations

An API Key is required. Clients can use their existing lifetime API key to access the information if required (however unlikely).
Data is sourced from the The Bureau of Infrastructure, Transport and Regional Economics (BITRE) and the Australian Bureau of Statistics. Where population data is unavailable we'll apply predictive growth rates based on migration numbers (usually around 3%).
The same data is returned for crashes (rather than fatalities). This information is returned via the crash endpoint and includes the age and sex of each individual.
If interested, we'll likely build a search and graphing feature on the ASJ website .
The API is new. If you encounter issues, errors, or you have any feature requests, please let us know.
There's about a dozen other databases we'll make available via an API. Subscribe to our mailing list or like us on Facebook to keep informed of changes.