Aircraft API Documentation - Version 1

Resources - Aircraft (Aircraft)

Aircraft represent an individual aircraft.

Resource model

Name	Property Name	Data Type	Optional	Description
Reason Code	`reason_code`	Integer	no	activity code
Speed	`speed`	Float	no	speed in knots
Altitude	`altitude`	Float	no	altitude in metres
UTC	`utc`	String	no	time in UTC of this fix
Track	`track`	Float	no	heading relative to true north, in degrees
Entered	`entered`	String	no	time in UTC of fix entry into database
Device ID	`device_id`	Float	no	ID of GPS unit
Vehicle ID	`vehicle_id`	Float	no	as above
ESN	`esn`	Integer	no	GPS unit serial number
Longitude	`longitude`	Float	no	longitude of fix in dec degrees
Latitude	`latitude`	Float	no	latitude of fix in dec degrees
Heading	`heading`	Integer	no	integer version of `track`
Callsign	`callsign`	String	no	callsign of aircraft

Resource representation - GeoJSON

This resource is returned as GeoJSON using the following structure:

The top level object will be a Feature Collection Object.
This will contain a number of Features each of which represent a single resource entity.
Geo-spatial information for this resource is represented as a Point using the latitude and longitude properties.
All other properties are included in a Properties object.

Example (GeoJSON)

        {
    "type": "FeatureCollection",
    "totalFeatures": 1,
    "features": [
		{
			"type": "Feature",
			"id": "latest_aircraft_positions.fid--132a67ac_150cce31355_-2da7",
			"geometry": {
				"type": "Point",
				"coordinates": [
				-68.1277,
				-67.56608
				]
			},
			"geometry_name": "latlong",
			"properties": {
				"altitude": 17.2,
				"device_id": 4658,
				"esn": 70002330,
				"heading": 315,
				"reason_code": 192,
				"speed": 2.73,
				"track": 315.35,
				"vehicle_id": 4658,
				"pk_id": 4067,
				"entered": "2015-11-07T16:36:34Z",
				"latitude": -67.56608,
				"longitude": -68.1277,
				"callsign": "VP-FAZ",
				"utc": "2015-11-07T16:36:18Z",
				"checktimestamp": "2015-11-09T10:50:06.091Z",
				"bbox": [
					-68.1277,
					-67.56608,
					-68.1277,
					-67.56608
				]
			}
		}
	],
	"crs": {
		"type": "name",
		"properties": {
		"name": "urn:ogc:def:crs:EPSG::4326"
		}
	},
	"bbox": [
		-67.56608,
		-68.1277,
		-67.56608,
		-68.1277
	]
}

      

Resource methods

[GET]/aircraft/position
[GET]/aircraft/position/{callsign}
[GET]/aircraft/position/{callsign}/{timestamp}
[GET]/aircraft/position/{callsign}/{timestamp1}/{timestamp2}
[GET]/aircraft/units

`[GET]/aircraft/position`

Returns all available aircraft current positions.

Traits

Trait	Enabled
Authenticated	Yes

Parameters

None.

Options

None.

Example request

URL: https://api.bas.ac.uk/aircraft/v1/aircraft/position/

Note: Interactive examples for this method may be covered in the examples document.

Headers

Key	Value
Content-Type	application/json
Accept	application/vnd.geo+json; q=1.0, application/json; q=0.5

Body (Raw)

N/A

Example response (200 OK)

Headers

Key	Value
Content-Type	application/vnd.geo+json

Body (GeoJSON)

Note: For brevity, only the first two records are shown.

        {
	"type": "FeatureCollection",
	"totalFeatures": 5,
	"features": [
		{
			"type": "Feature",
			"id": "latest_aircraft_positions.fid--132a67ac_150cce31355_-2da5",
			"geometry": {
				"type": "Point",
				"coordinates": [
					-68.12858,
					-67.563934
				]
			},
			"geometry_name": "latlong",
			"properties": {
				"altitude": -15.8,
				"device_id": 4734,
				"esn": 70002364,
				"heading": 4,
				"reason_code": 130,
				"speed": 0.3,
				"track": 4.22,
				"vehicle_id": 4734,
				"pk_id": 3946,
				"entered": "2015-11-06T17:37:38Z",
				"latitude": -67.563934,
				"longitude": -68.12858,
				"callsign": "VP-FBC",
				"utc": "2015-11-06T17:37:26Z",
				"checktimestamp": "2015-11-09T11:00:04.779Z",
				"bbox": [
					-68.12858,
					-67.563934,
					-68.12858,
					-67.563934
				]
			}
		},
		{
			"type": "Feature",
			"id": "latest_aircraft_positions.fid--132a67ac_150cce31355_-2da4",
			"geometry": {
				"type": "Point",
				"coordinates": [
					-68.1277,
					-67.56608
				]
			},
			"geometry_name": "latlong",
			"properties": {
				"altitude": 17.2,
				"device_id": 4658,
				"esn": 70002330,
				"heading": 315,
				"reason_code": 192,
				"speed": 2.73,
				"track": 315.35,
				"vehicle_id": 4658,
				"pk_id": 4067,
				"entered": "2015-11-07T16:36:34Z",
				"latitude": -67.56608,
				"longitude": -68.1277,
				"callsign": "VP-FAZ",
				"utc": "2015-11-07T16:36:18Z",
				"checktimestamp": "2015-11-09T11:00:04.779Z",
				"bbox": [
					-68.1277,
					-67.56608,
					-68.1277,
					-67.56608
				]
			}
		},
	...
	],
	"crs": {
		"type": "name",
		"properties": {
		"name": "urn:ogc:def:crs:EPSG::4326"
		}
	},
	"bbox": [
		-74.85875,
		-71.57432,
		-67.563934,
		-68.1273
	]
}

      

`[GET]/aircraft/position/{callsign}`

Returns a specified aircraft’s current position by its callsign.

Traits

Trait	Enabled
Authenticated	Yes

Parameters

Name	Field Name	Data Type	Required	Valid Value(s)	Description
Callsign	`{callsign}`	String	Yes	A valid `callsign`	Used to specify which aircraft to return

Options

None.

Example request

URL: https://api.bas.ac.uk/aircraft/v1/aircraft/position/VP-FAZ

Note: Interactive examples for this method may be covered in the examples document.

Headers

Key	Value
Content-Type	application/json
Accept	application/vnd.geo+json; q=1.0, application/json; q=0.5

Body (Raw)

N/A

Example response (200 Success)

Headers (Redundant headers removed)

Key	Value
Content-Type	application/vnd.geo+json

Body (GeoJSON)

        {
    "type": "FeatureCollection",
    "totalFeatures": 1,
    "features": [
		{
			"type": "Feature",
			"id": "latest_aircraft_positions.fid--132a67ac_150cce31355_-2da7",
			"geometry": {
				"type": "Point",
				"coordinates": [
				-68.1277,
				-67.56608
				]
			},
			"geometry_name": "latlong",
			"properties": {
				"altitude": 17.2,
				"device_id": 4658,
				"esn": 70002330,
				"heading": 315,
				"reason_code": 192,
				"speed": 2.73,
				"track": 315.35,
				"vehicle_id": 4658,
				"pk_id": 4067,
				"entered": "2015-11-07T16:36:34Z",
				"latitude": -67.56608,
				"longitude": -68.1277,
				"callsign": "VP-FAZ",
				"utc": "2015-11-07T16:36:18Z",
				"checktimestamp": "2015-11-09T10:50:06.091Z",
				"bbox": [
					-68.1277,
					-67.56608,
					-68.1277,
					-67.56608
				]
			}
		}
	],
	"crs": {
		"type": "name",
		"properties": {
		"name": "urn:ogc:def:crs:EPSG::4326"
		}
	},
	"bbox": [
		-67.56608,
		-68.1277,
		-67.56608,
		-68.1277
	]
}

      

Example response (400 Bad Request)

Using URL: https://api.bas.ac.uk/aircraft/v1/aircraft/position/NONE.

Headers (Redundant headers removed)

Key	Value
Content-Type	application/json

Body

        {
	"status": 400,
	"detail": "NONE is not a valid aircraft callsign"
}

      

`[GET]/aircraft/position/{callsign}/{timestamp}`

Returns an aircraft’s position by callsign at a specific timestamp.

Traits

Trait	Enabled
Authenticated	Yes

Parameters

Name	Field Name	Data Type	Required	Valid Value(s)	Description
Callsign	`{callsign}`	String	Yes	A valid `callsign`	Used to specify which aircraft to return
Timestamp	`{timestamp}`	ISO Date	Yes	ISO `timestamp`	Indicates date/time when position required

Options

None.

Example request

URL: https://api.bas.ac.uk/aircraft/v1/aircraft/position/VP-FBQ/2015-11-06 00:00:00

Note: Interactive examples for this method may be covered in the examples document.

Headers

Key	Value
Content-Type	application/json
Accept	application/vnd.geo+json; q=1.0, application/json; q=0.5

Body (Raw)

N/A

Example response (200 Success)

Headers (Redundant headers removed)

Key	Value
Content-Type	application/vnd.geo+json

Body (GeoJSON)

        {
	"type": "FeatureCollection",
	"totalFeatures": 1,
	"features": [
		{
			"type": "Feature",
			"id": "aircraft_positions.3918",
			"geometry": {
				"type": "Point",
				"coordinates": [
					-70.84787,
					-53.003872
				]
			},
			"geometry_name": "latlong",
			"properties": {
				"altitude": 33.7,
				"device_id": 11334,
				"esn": 70002451,
				"heading": 269,
				"reason_code": 129,
				"speed": 1.9,
				"track": 269.65,
				"vehicle_id": 11522,
				"pk_id": 3918,
				"entered": "2015-11-04T23:44:17Z",
				"latitude": -53.003872,
				"longitude": -70.84787,
				"callsign": "VP-FBQ",
				"utc": "2015-11-04T23:44:07Z",
				"checktimestamp": "2015-11-06T15:40:09.434Z",
				"bbox": [
					-70.84787,
					-53.003872,
					-70.84787,
					-53.003872
				]
			}
		}
	],
	"crs": {
		"type": "name",
		"properties": {
			"name": "urn:ogc:def:crs:EPSG::4326"
		}
	},
	"bbox": [
		-53.003872,
		-70.84787,
		-53.003872,
		-70.84787
	]
}

      

Example response (400 Bad Request)

Using URL: https://api.bas.ac.uk/aircraft/v1/aircraft/VP-FBQ/2015-10-05.

Headers (Redundant headers removed)

Key	Value
Content-Type	application/json

Body

        {
	"status": 400,
	"detail": "invalid date - should be yyyy-MM-dd hh:mm:ss"
}

      

`[GET]/aircraft/position/{callsign}/{timestamp1}/{timestamp2}`

Returns an aircraft’s positions by callsign between two timestamps.

Traits

Trait	Enabled
Authenticated	Yes

Parameters

Name	Field Name	Data Type	Required	Valid Value(s)	Description
Callsign	`{callsign}`	String	Yes	A valid `callsign`	Used to specify which aircraft to return
Timestamp1	`{timestamp1}`	ISO Date	Yes	ISO `timestamp`	Start of interval
Timestamp2	`{timestamp2}`	ISO Date	Yes	ISO `timestamp`	End of interval

Options

None.

Example request

URL: https://api.bas.ac.uk/aircraft/v1/aircraft/position/VP-FBQ/2015-11-01 00:00:00/2015-11-06 00:00:00

Note: Interactive examples for this method may be covered in the examples document.

Headers

Key	Value
Content-Type	application/json
Accept	application/vnd.geo+json; q=1.0, application/json; q=0.5

Body (Raw)

N/A

Example response (200 Success)

Note: For brevity, only the first record is shown.

Headers (Redundant headers removed)

Key	Value
Content-Type	application/vnd.geo+json

Body (GeoJSON)

        {
	"type": "FeatureCollection",
	"totalFeatures": 182,
	"features": [
		{
			"type": "Feature",
			"id": "aircraft_positions.3349",
			"geometry": {
				"type": "Point",
				"coordinates": [
					-70.84907,
					-53.00395
				]
			},
			"geometry_name": "latlong",
			"properties": {
				"altitude": 40.7,
				"device_id": 11334,
				"esn": 70002451,
				"heading": 169,
				"reason_code": 129,
				"speed": 0.06,
				"track": 169.45,
				"vehicle_id": 11522,
				"pk_id": 3349,
				"entered": "2015-11-01T07:49:27Z",
				"latitude": -53.00395,
				"longitude": -70.84907,
				"callsign": "VP-FBQ",
				"utc": "2015-11-01T07:48:58Z",
				"checktimestamp": "2015-11-01T07:50:04.531Z",
				"bbox": [
					-70.84907,
					-53.00395,
					-70.84907,
					-53.00395
				]
			}
		},
	...
	],
	"crs": {
		"type": "name",
		"properties": {
		"name": "urn:ogc:def:crs:EPSG::4326"
		}
	},
	"bbox": [
		-74.94534,
		-71.848465,
		-52.99835,
		-68.05719
	]
}

      

Example response (400 Bad Request)

Using URL: https://api.bas.ac.uk/aircraft/v1/aircraft/VP-FBQ/2015-10-05 00:00:00/2015-10-04 00:00:00.

Headers (Redundant headers removed)

Key	Value
Content-Type	application/json

Body

        {
	"status": 400,
	"detail": "2015-10-04 00:00:00 is before 2015-10-05 00:00:00"
}

      

`[GET]/aircraft/units`

Returns GPS unit metadata for all available aircraft.

Note: This resource method uses a JSON rather than GeoJSON representation.

Traits

Trait	Enabled
Authenticated	Yes

Parameters

None.

Options

None.

Example request

URL: http://api.bas.ac.uk/aircraft/v1/aircraft/units/

Note: Interactive examples for this method may be covered in the examples document.

Headers

Key	Value
Content-Type	application/json
Accept	application/json

Body (Raw)

N/A

Example response (200 OK)

Headers

Key	Value
Content-Type	application/json

Body (JSON)

        {
    "data": [
        {
            "id": "70002330",
            "esn": "70002330",
            "connect_interval": 600,
            "imei": "300224010244920",
            "name": "VP-FAZ",
            "unit_type": "S200",
            "type": "S200",
            "config_updated": "2012-10-03 03:33:23.0"
        },
        {
            "id": "70002351",
            "esn": "70002351",
            "connect_interval": 600,
            "imei": "300025010628330",
            "name": "VP-FBL",
            "unit_type": "S200",
            "type": "S200",
            "config_updated": "2012-10-03 03:33:23.0"
        },
        {
            "id": "70002362",
            "esn": "70002362",
            "connect_interval": 600,
            "imei": "300025010326090",
            "name": "VP-FBB",
            "unit_type": "S200",
            "type": "S200",
            "config_updated": "2012-10-03 03:33:23.0"
        },
        {
            "id": "70002364",
            "esn": "70002364",
            "connect_interval": 600,
            "imei": "300025010326060",
            "name": "VP-FBC",
            "unit_type": "S200",
            "type": "S200",
            "config_updated": "2012-10-03 03:33:23.0"
        },
        {
            "id": "70002451",
            "esn": "70002451",
            "connect_interval": 0,
            "imei": "300025010333140",
            "name": "VP-FBQ",
            "unit_type": "S200",
            "type": "S200",
            "config_updated": "2000-01-01 00:00:00"
        }
    ]
}

      

This information may be out of date whilst this website is being redeveloped. Until then, if you have any problems using an API documented here, please contact the relevant project maintainer.