API
It's your data, use it, share it.
 

Overview

If you would like to integrate the data stored on our servers with other applications, display it on your website, or offer it to others, you can do so using our REST API to access your data. The API is an authenticated read-only view into your groups's aircraft, logs and position reports. All returned data is in a single JSON object. If you run into problems or have questions, we are here to help. Just send an email to support@airbly.com.

Commands available

Command Description
assetList Returns a list of assets (aircraft) with their associated log enties and position reports.
webhook An method of automatically pushing assetList content to an endpoint when any asset or it's associated log entries or position reports change.

Sample data

We have setup a sample group ("API-Test") which you can use to see how the API commands function. This group contains two aircraft, each with a few log entries. The keys and UUIDs for the test data are:

   Group uuid: 00000001-4444-1100-0000-000000000001
   Group key: 9C4NSsnLig3zlgzPHqLkXwHPtKv7OC
   N44API uuid: 00000001-4444-2000-8846-001471040618
   N88API uuid: 00001000-4444-2000-5574-001522329325

Data types

The API will process and respond using the following data types:

Type Description Example
boolean true or false true
integer signed, whole 64-bit number between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,808 1234
string series of characters abc_123
hex a series of hex characters [0123456789abcdef] 014bdf15
uuid A 128-bit UUID 00000001-4444-2000-8846-001471040618
timestamp number of milliseconds since January 1, 1970. 1579290559000 (2020-Jan-17 @ 19:49:19.000 UTC)
object an object with zero or more values { "x": 1, "y": 2 }
array a grouping of several values with the same data type [1, 2, 3]

Group authentication key


All requests require a valid group API key to be sent as part of the request (groupKey=9C4NSsnLig3zlgzPHqLkXwHPtKv7OC for example). This key can be generated in the Airbly web application on the group page by a user with Administrator access to the group. Everytime a new key is generated, the old one is invalidated. There can only be one valid API key per group at a time.

Request

API requests at made to the following URL, with these minimum arguments:
https://airbly.com/api/v3/assetList?groupKey=9C4NSsnLig3zlgzPHqLkXwHPtKv7OC

You should replace assetList with the API command you would like to execute.
You should replace 9C4NSsnLig3zlgzPHqLkXwHPtKv7OC with your group's key

Arguments may be sent as either GET or POST values. For example, this URL will request just the N44API aircraft:
https://airbly.com/api/v3/assetList?groupKey=9C4NSsnLig3zlgzPHqLkXwHPtKv7OC&asset_uuids=00000001-4444-2000-8846-001471040618

Response

The API endpoint will respond with a JSON object. The complete contents of this object will vary based on the command executed, but there are several fields which are included in every request. Those are:

Fields

Name Data type Description
cmd string The command executed
cmd_exec_time_ms integer The number of milliseconds it took the server to process the command
error string Human readable description of any errors during processing
auth_group_success boolean True if the group API key was valid
auth_group_id uuid UUID of the group the request authenticated as
server_timestamp timestamp Current timestamp on the server
server_available boolean This will be set to false if the server is unavailable due to maintenance
server_message_timestamp timestamp The timestamp the server_message was created
server_message string Human readable message from the server - used to make announcements or inform of upcoming maintenance
__cmd_executed__ object The response created by the command which was executed. It will have a name which matches the command.
"cmd": "assetList",
"cmd_exec_time_ms": 472,
"error": "",
"auth_group_success": true,
"auth_group_id": "00000001-4444-1100-1940-001461853639",
"server_timestamp": 1579287172000,
"server_available": true,
"server_message_timestamp": 0,
"server_message": "",
"assetList": { }
                                

assetList API command

The assetList API command is used to return a list of assets, their usage logs and position reports. The response data can be filtered by passing arguments via GET or POST. Here is an example of the assetList API call: https://airbly.com/api/v3/assetList?groupKey=9C4NSsnLig3zlgzPHqLkXwHPtKv7OC

Arguments

The following arguments maybe used with the assetList API call. Logs are only returned for matched assets. Points are only returned for matched logs with matched assets.

Name Datatype Default Description
groupKey uuid required The group's API key.
asset_uuids uuid '' Return assets with the following comma separated uuids. Leaving this field blank will match all assets.
asset_types string all Return assets of this type Valid values are: all, aircraft
asset_updated_after timestamp 0 Return assets updated after this timestamp.
asset_updated_before timestamp 9223372036854775808 Return assets updated before this timestamp.
log_types string none Return logs with the following comma separated types. Valid values are: none, all, flight, maint
log_uuids uuid '' Return logs with the following comma separated uuids. Leaving this field blank will match all logs.
log_updated_after timestamp 0 Return logs updated after this timestamp.
log_updated_before timestamp 9223372036854775808 Return logs updated before this timestamp.
log_completed_after timestamp 0 Return logs completed after this timestamp.
log_completed_before timestamp 9223372036854775808 Return logs completed before this timestamp.
log_limit_per_asset integer 10 Return at most this number of logs. Newest logs are first
point_types string none Return points with the following comma separated types. Valid values are: none, all, first, last

Example

To retrieve the 5 most recent flights with the start and end points from all assets in our sample group:
https://airbly.com/api/v3/assetList?groupKey=9C4NSsnLig3zlgzPHqLkXwHPtKv7OC&log_types=flight&log_limit_per_asset=5&point_types=first,last

Response

The response will be an array of asset objects and relevant sub-objects. Below you will find a description of each of these object types and fields.

asset object

This object describes a particular asset.

Name Datatype Description
uuid uuid UUID of the asset
created_at timestamp Created
updated_at timestamp Last changed
asset_type string Type. Valid values: aircraft
parrent_uuid uuid UUID of the parrent asset
children_uuid uuid UUID of any children assets
ident string Identifier, such as the tail number.
make string Make
model string Model
year integer Year of manufacture
serial_number string Serial number
description string Optional description
operational_status string Most recent operational status. Valid values: stopped, inflight, sos, disabled
attention_status string Overall attention required status. Valid values: none, required
maintenance_status string Overall maintenance status. Valid values: current, due, overdue
usage object This is the total usage at the time the API command was executed. See the usage object definition.
device object This is the device which is currently assigned to this asset. See the device object definition.
logs array List of log entries for this asset, filtered based on the arguments used. See log object definition.
{
    "uuid": "00004000-4444-2000-6311-001551812065",
    "created_at": 1551812065000,
    "updated_at": 1575643428000,
    "asset_type": "aircraft",
    "parrent_uuid": "00000000-0000-0000-0000-000000000000",
    "children_uuid": [],
    "ident": "D10-7978",
    "make": "C100",
    "model": "Archives",
    "year": 2019,
    "serial_number": "",
    "description": "Test",
    "operational_status": "stopped",
    "attention_status": "none",
    "maintenance_status": "none",
    "usage": { usage object }
    "device": { device object }
    "logs": [ log objects ]
}
                            

log object

This object describes a log entry. These entries can either be flight logs or maintenance logs.

Name Datatype Description
uuid uuid UUID of the log entry
created_at timestamp Created
updated_at timestamp Last changed
log_type string Type of log entry. Valid values: flight, maint.
status string Log entry status. Valid values: inflight, sos, closed, striked
happened_at timestamp When did this log occur. Time and date are end or completion times.
attention_required boolean Attention required flag
remarks string Option remarks and notes
route object See the route object definition.
personel array Array of personel associated with this log entry. See the personel object definition.
device object The device which created this log entry if the entry was created automatically. See device object definition.
sync object The most recent syncronization event. See sync object definition.
usage object Usage recorded by this log entry. See usage object definition.
events array An array of events which where created during the log entry. Valid values: sos, g_exceeded, pitch_roll_exceeded, climb_descent_exceeded, device_restart, device_powered_off.
points array Points which make up this log entry. See points object definition.
custom array Custom values
{
    "uuid": "00004000-4444-2000-6311-001551812065",
    "created_at": 1551812065000,
    "updated_at": 1575643428000,
    "log_type": "flight",
    "status": "closed",
    "happened_at": 1579899600000,
    "attention_required": true,
    "remarks": "",
    "route": { route object },
    "personel": [ personel objects ],
    "device": { device object },
    "sync": { sync object },
    "usage": { usage object },
    "events": { events object },
    "points": [ points objects ],
    "custom": [ custom data ]    
}
                            

point object

This object describes a point entry.

Name Datatype Description
uuid uuid UUID of the point entry
happened_at timestamp When the point was recorded
synced_at timestamp If the point was created as a result of a post-flight synchronization, this will be the time that synchronization happened. Otherwise it will be 0
point_type string Type of point. Valid values: start, event, inroute, limited, stop.
latitude string Latitude of the point in decimal degrees.
longitude string Longitude of the point in decimal degrees.
altitude integer Altitude in feet above sea level.
sensors object Values from sensors. Only available after a post-flight synchronization. See sensor object definition.
events array An array of events which where created during the point creation. Valid values: sos, g_exceeded, pitch_roll_exceeded, climb_descent_exceeded, device_restart, device_powered_off, movement_start, movement_stop, takeoff, landing.
{
    "uuid": "03b74444-0000-4200-016f-85a589b600f9",
    "happened_at": 1578057089000,
    "synced_at": 0,
    "point_type": "start",
    "latitude": 46.2797,
    "longitude": -63.1273,
    "altitude": 200,
    "sensors": {},
    "events": [ "takeoff" ]
}
                            

usage object

This object describes either the total usage or time logged to the parrent to date such as the total times on an aircraft, or the incremental amount of time logged for the parrent activity, such as a flight. Only the fields appropriate to the parrent object and group settings will be included.

Name Datatype Description
usage_type string Type of usage. Valid values: total, incremental.
engine_seconds integer Seconds of engine (hobbs) time.
air_seconds integer Seconds of air time (time in service).
tach_seconds integer Seconds of tachometer time.
landings integer Number of landings.
cycles integer Number of cycles (engine start/stop).
movements integer Number of movements between hovering events.
engine_start_at timestamp Engine started at.
engine_stop_at timestamp Engine stopped at.
block_start_at timestamp Off blocks at.
block_stop_at timestamp On blocks at.
air_first_takeoff timestamp First takeoff at.
air_last_landing timestamp Last landing at.
fuel_ml integer Fuel consumed in mL
oil_ml timestamp Oil consumed in mL
{
    "type": "incremental",
    "engine_seconds": 3600,
    "air_seconds": 2400,
    "tach_seconds": 3000,
    "landings": 17,
    "cycles": 0,
    "movements": 0,
    "engine_start_at": 1578055517000,
    "engine_stop_at": 1578057089000,
    "block_start_at": 1578055644000,
    "block_stop_at": 1578056907000,
    "air_first_takeoff": 1578055644000,
    "air_last_landing": 1578056907000,
    "fuel_ml": 0,
    "oil_ml" : 0
}
                            

device object

This object describes either the device assigned to an object or the device which created the object. Only the fields appropriate to the parrent object and group settings will be included.

Name Datatype Description
uuid uuid UUID of the device assigned to this asset.
serial_number string Serial of the device. Format: P200-1234567.
firmware_version integer Current firmware version installed.
battery string Device battery status. Valid values: good, low
last_sync_at timestamp Last post-flight syncronization event for this device.
{
    "uuid": "00000001-4444-3000-7877-001460749906",
    "serial_number": "P100-2327557",
    "firmware_version": 58,
    "battery": "low",
    "last_sync_at": 1531747012000,
}
                            

route object

This object describes the route an asset took to create the parrent log entry.

Name Datatype Description
departure_ident string Airport identifier the asset departed from.
arrival_ident string Airport identifier the asset arrived at.
{
    "departure_ident": "CYYG",
    "arrival_ident": "CYSU"
}
                            

personel object

This object describes the person(s) assocaited with the creation of the log entry.

Name Datatype Description
uuid uuid UUID of the user
fullname string Full name of the user
type string Type of personel. Valid values: pic, sic, mechanic.
{
    "uuid": "00000001-4444-1000-3295-001453387958",
    "fullname": "Chris VanHorn",
    "type": "mechanic"
}
                            

sync object

This object describes the most recent syncronization event for the parrent entry.

Name Datatype Description
type string The type of synchronization which occured. Valid values: log, full
happened_at timestamp When this synchronization occurred
by_device_serial_number string Serial number of the device which performed the synchronization.
{
    "type": "log",
    "happened_at": 1578057089000,
    "by_device_serial_number": "H100-1000002"
}
                            

sensor object

This object describes values recorded from the device sensors at the time the parrent object was recorded.

Name Datatype Description
g_force float Vertical g-force. Range is -8.0 to +8.0, incremented in tenths.
pitch_angle integer Pitch angle in degrees. Range is -90 to +90.
roll_angle integer Roll angle in degrees. Range is -180 to +180.
vertical_speed integer Vertical speed in feet per minute (fpm)
ground_speed integer Ground speed in knots
heading integer Heading in degrees.
bearing integer Bearing in degrees.
temperature integer Ambient temperature in degrees Celsius. Range is -40C to +87C.
gps_satellite_count integer Number of satellites used to calculate position.
vibration integer Not described at this time.
    {
        "g_force": 1,
        "pitch_angle": 0,
        "roll_angle": 0,
        "vertical_speed": 0,
        "ground_speed": 0,
        "heading": 0,
        "bearing": 0,
        "temperature": 0,
        "gps_satellite_count": 16,
        "vibration": 10000
    }
                                

Overview

Webhooks allow our system to automatically push asset, log and point data to your system when they change. For example, when one of our monitoring devices closes out a flight log, our system can automatically send that log to your system. The webhook will be sent within 60 seconds of an update to an asset, log or point. If multiple objects have changed since the last post, multiple entries will be included in the single webhook post.

Configuration


To enable webhooks, you will need to set the endpoint where you would like the data to be sent. This should be in the form of a web URL. This can be set on the group settings page in our application. If you would like to disable the webhook, simply erase the web URL can click save.

POST Data format

The webhook will post a JSON object to your endpoint. That object is the equivalent to calling the assetList API command with the following arguments:

asset_types=all
asset_updated_after=timestamp of the oldest entry in the last webhook post
log_types=all
log_updated_after=timestamp of the oldest entry in the last webhook post
log_limit_per_asset=999
point_types=first,last
                    

Expected response

The webhook will continue to retry every 60 seconds until a valid confirmation is received at the end of the POST. The response from your system should be a JSON object with the following fields.

Name Datatype Description
cmd string The webhook command. Valid values: webhookAssetList.
group_uuid uuid UUID of the group sent.
server_timestamp timestamp Timestamp of your server. Used for performance monitoring.
asset_count integer The number of assets you were sent and processed.
error string Any error messages. If this field is not empty, we will consider the webhook post to have failed and will try again later.
{
    "cmd": "webhookAssetList",
    "group_uuid": "00000000-0000-0000-0000-000000000000",
    "server_timestamp": 1580498821000,
    "asset_count": 4,
    "error": ""
}
                            

Sample code

This sample code is written in PHP and demonstrates how your endpoint should reply to a webhook post.

<?php

// Initialize our response
$response = new stdClass();
$response->cmd = 'unknown';
$response->group_uuid = '00000000-0000-0000-0000-000000000000';
$response->server_timestamp = time();
$response->asset_count = 0;
$response->error = '';

// Process the data
try {

    // Collect the post data
    $post_raw = file_get_contents("php://input");
    if (!$post_raw) throw new Exception('No data was received');

    // Decode the JSON into a PHP object
    $post_decoded = json_decode($post_raw);
    if (!$post_decoded) throw new Exception('Invalid json data received');

    // Collect the group UUID
    if (!isset($post_decoded->group->uuid)) throw new Exception('No group uuid was received');
    $response->group_uuid = $post_decoded->group->uuid;

    // Collect the command
    if (!isset($post_decoded->cmd)) throw new Exception('No cmd was received');
    $response->cmd = $post_decoded->cmd;

    // Verify the command
    if ($response->cmd != 'webhookAssetList') throw new Exception('Invalid command was received');

    // Did we receive any assets
    if (!isset($post_decoded->assets) OR !is_array($post_decoded->assets)) throw new Exception('No assets were received');

    // Step through the aircraft
    foreach ($post_decoded->assets AS $asset {
        $response->asset_count++;

        // -- YOUR CUSTOM CODE HERE TO PROCESS THE ASSET --

    }

    // Catch our errors
    } catch (Exception $e) {
        $response->error = $e->getMessage();
        http_response_code(400);
    }

    // Return a JSON object response
    $response_json = json_encode($response);
    header('Content-type: application/json');
    echo $response_json;
?>