Regarding the User’s Flights API, the flights endpoint is secured with OAuth. This article will describe accessing the flights endpoints and importing a flight into a user’s account. To request access to the APIs, contact team@cloudahoy.com.
Accessing the Flights Endpoint
The /flights endpoint is available at
https://www.cloudahoy.com/integration/v1/flights
All requests to OAuth-secured endpoints must include an Authorization header, which provides the access token on behalf of which the request is being made:
Authorization: Bearer <user's access token>
The token must authorize the flights:read scope to read the user’s flights.
Getting a User’s Flights
Executing an HTTP GET on the flights endpoint, providing the appropriate access token, will return all flights in a user’s account for which the user is a crew member. It does not return any flights shared with the user via direct share or group membership. GET requests to the /flights endpoint require the flights:read OAuth scope.
Query String Parameters
The list of returned flights may be filtered using the following query string parameters:
| Parameter | Type | Description |
|---|---|---|
page |
integer | The 1-based page number of results to be retrieved, based on pageSize |
pageSize |
integer |
Optional The number of flights to include in a page of results. The maximum allowed value is |
start |
integer |
Optional The date/time, specified in seconds since epoch GMT, of the earliest flight that will be returned in the result set. The result set will start with the user’s earliest flight if not provided. |
end |
integer |
Optional The date/time, specified in seconds since epoch GMT, of the most recent flight that will be returned in the result set. If not provided, the current date/time is assumed. |
role |
string |
Optional Specifies the role the user must have in the returned flights. For example, specifying |
thumbnailWidth |
integer |
Optional The width, in pixels, of the thumbnail image of each flight. Note that the images have a fixed W:H ratio of |
A successful request will result in a 200 status code and an array of flight objects.
See CloudAhoy Flight Return Object API for more information on the flight object.
Importing a Flight
Executing an HTTP POST on the flights endpoint, providing the appropriate access token, a properly formatted CSV file, GPX file, or KML file, and some flight metadata will import the flight into the account of the user indicated by the access token.
When importing a CloudAhoy-formatted CSV file, the entire flight’s data can be uploaded in one file, or the upload can be incremental. For example, a 12-hours flight can be split into four files, three hours each. All the files must have identical metadata (see the CloudAhoy CSV File Format).
When importing a GPX or KML file, the data for the entire flight must be present in the file.
POST requests to the /flights endpoint require the flights:import OAuth scope
Form Fields
The CloudAhoy-formatted CSV file, KML file, or GPX file to import must be specified by the IMPORT form field of the post.
A JSON-formatted string containing metadata about the flight must be specified by the METADATA form field of the post. The properties of the metadata are described in the following table:
Metadata Object
| Property | Type | Description |
|---|---|---|
importerVersion |
string | Required The version of the importing software. This is free text and, ideally, should change with each release of the application performing the import |
owner |
object | Optional An object containing the properties:
role is one of : Pilot, Copilot, Student, Instructor, Passenger, Safety Pilot, ExaminerFlags is an optional sub-object containing any combination of these properties: pic, solo, or checkride, with a boolean values indicating with the owner was the Pilot in command, on a solo flight, or on a checkride, respectively. Any property not provided will default to false.Note: the owner and other may not have the same role. a 400 error will be generated if they do.Note: the owner and crew may not have any of the same flags set to true. a 400 error will be generated if they do.Examples:
|
other |
object | Optional An object containing the properties:
name is the name or email address of the second occupant of the aircraft. If an email address is specified, and that email address corresponds to a CloudAhoy user that is a buddy of the owner, the flight will also appear in the account of the buddy.role is one of the following: Pilot, Copilot, Student, Instructor, Passenger, Safety Pilot, ExaminerFlags is an optional sub-object containing any combination of these properties: pic, solo, or checkride, with a boolean values indicating with the owner was the Pilot in command, on a solo flight, or on a checkride, respectively. Any property not provided will default to false.Note: the owner and crew may not have the same role. a 400 error will be generated if they do.Note: the owner and crew may not have any of the same flags set to true. a 400 error will be generated if they do.Examples:
|
tail |
string | Optional The tail number of the aircraft flown during the flight. If not provided, it defaults to *UNK |
remarks |
string | Optional Remarks about the flight. |
For example, the following shell command uses curl to import the file /tmp/my_flight.csv:
$ curl -F "IMPORT=@/tmp/my_flight.csv" \
-F 'METADATA={"importerVersion":"v1.23.4"}' \
-H "Authorization: Bearer <user's access token>" \
https://www.cloudahoy.com/integration/v1/flights
Return Value
A successful import will result in the following return object:
| Parameter | Type | Description |
|---|---|---|
key |
string | A temporary key that allows the flight to be immediately debriefed |
status |
string | Indication of success: OK |
flightId |
string | The ID of the uploaded flight in the user’s account. Note: This flightId is not globally unique. It is unique within the user’s account. |
error |
string | Present and populated only if the flight was successfully imported, but there are problems that make it not debriefable (such as no airborne segments or too few data points). The value returned indicates the problem. |
Be aware that the import can be successful, but the flight cannot be debriefed. This may occur if no airborne segments are detected in the flight or if there are too few data samples. In these cases, the error property will be present and populated in the object returned by the import.
The key returned may be used for a period of time to link directly to the flight:
http://www.cloudahoy.com/debrief/?key=<imported flight key>
If the request or flight data file is malformed, an HTTP status of 400 will be returned, with a text description of the problem.
Last Updated: