Flytrex Live OAuth API

This API provides access to user’s Flytrex account data, and live-flight information, received in real time from the Flytrex Live black-box. Using the API developers can build new means for tracking consumer drones in real-time.

The API uses OAuth2 for authentication. Developers can obtain information about individual pilots, and other pilots who authorized the app, ideal for the development of tools that require tracking multiple drones together or social-style tools.

​Our team continuously works ​on new improvements to the API and we'd love to get your feedback and ideas. Feel free to email our team at: developers@flytrex.com with suggestions and feedback.

Registering a New Flytrex App

To get started, you will need to create a Flytrex app. Currently, app registration is done manually, in order to help us work more closely with developers using our API, and to continue improving the API.

Please email us at developers@flytrex.com if looking to set up a new Flytrex app, and our team will send you the OAuth information needed to get started, once we have received the relevant details from you.

OAuth2 Authorization Code Flow

Before your app can make any calls to the Flytrex API it needs to request permission from the user to access their Flytrex data. In this section we'll cover the steps needed to request such authorization from the user, that will eventually provide your app with access and refresh tokens needed to make calls to the Flytrex Live API.

Step 1: App request authorization

To initiate the OAuth2 authorization process your app sends the user to the Flytrex Request Authorization link. This displays a page with details about your app and requesting the user’s permission to share their Flytrex account information with the app, similar to the permission-request used in services such as Facebook, Twitter etc.

URL STRUCTURE

Redirect the user to the following URL:

http://www.flytrex.com/api/oauth2/o/authorize/?client_id=%APP_CLIENT_ID%&redirect_uri=%APP_REDIRECT_URI%&response_type=code

%APP_CLIENT_ID% - Your App client ID. You will receive your Client ID and Client Secret from us when registering a new app manually (See point #1 how to register a new app).

%APP_REDIRECT_URI% - Your App redirect URI as you provided when registering your new Flytrex OAuth2 app.

Step 2: User is asked to authorize app

The Flytrex Request Authorization page then presents to the user details about your app and the permissions it is requesting.

If the user is not logged in, they will be prompted to do so before they can authorize the app.

Step 3: User is redirected to app

Once the user has authorized the app, the OAuth2 engine redirects back to the redirect-uri you provided when first creating the Flytrex OAuth app. The Flytrex servers then performs a GET call to the redirect-uri passing a 'code' parameter.

Step 4: Your app requests refresh and access tokens

In this stage you should replace the app-code sent to your app’s redirect-uri with an access and refresh tokens. Using the app-code you just received, you will need to exchange it with an access and refresh token by making a POST request to its /api/token endpoint:

URL STRUCTURE

http://www.flytrex.com/api/oauth2/o/access_token/

IMPLEMENTATION

Here is a simple Python script that processes the data received in the redirect URL for our OAuth2 Flytrex app and exchanges the app-code with access and refresh tokens.


code = request.GET.get('code', '')

print code
r = requests.post('http://www.flytrex.com/api/oauth2/o/access_token/', dict(
    grant_type = 'authorization_code',
    code = code,
    redirect_uri = app_redirect_url,
    client_id = client_id,
    client_secret = client_secret
))

return HttpResponse(r.text)
                

Step 5: Tokens received

In response to the access-token call you will receive a JSON including your access and refresh token with the following structure:


{
    "access_token": "dt4b08125c7931a8g8e46243cyt26af1c85f",
    "token_type": "Bearer",
    "expires_in": 31535999,
    "refresh_token": "53e7bd30d4b379cjh393235dccajt5d4ed30",
    "scope": "read"
}
                

Once you have the access token you can use this to call any of the Flytrex Live web API calls outlined in the next section.

Flytrex Live API Calls

api/oauth2/1/account/info/

DESCRIPTION

Returns current user account info.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/account/info/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/account/info/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

RESPONSE

JSON including info about pilot’s account. Sample JSON result:

{
    "username":"jasonperr32",
    "first_name":"Jason",
    "last_name":"Perr"
    "display_name":"Jason Perr",
    "uid":29473,
    "email":"jasonperr@gmail.com",
    "profile_url":"http://www.flytrex.com/jasonperr32/",
    "flight_stats":
        {   "mission_max_ascent":21900.8096,
            "mission_max_altitude":20786.5655,
            "mission_max_speed":2089.792573,
            "mission_max_distance":0.0007021319588249739
        }
}
                

mission_max_ascent in meters
mission_max_altitude in meters
mission_max_speed in cm/s
mission_max_distance in earth radius units (1 = 3960 mile)

api/oauth2/1/account/info-extended/

DESCRIPTION

Returns current user extended account info. Similar to account/info/ call, but includes 'live' boolean flag indicating if the user is currently in a live flight, and a list of the user's live-devices with last-seen details for each device.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/account/info-extended/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/account/info-extended/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

RESPONSE

JSON including info about pilot’s account. Sample JSON result:

{
    "username":"jasonperr32",
    "first_name":"Jason",
    "last_name":"Perr"
    "display_name":"Jason Perr",
    "uid":29473,
    "email":"jasonperr@gmail.com",
    "profile_url":"http://www.flytrex.com/jasonperr32/",
    "live": false,
    "live_devices": [
        {   "aircraft":"Sky",
            "live":false,
            "hardware_version":"Sky",
            "uid":3270
            "last_seen": {  "temperature": 26,
                            "flight_mode": 1,
                            "long": "149.1652248",
                            "ground_speed": "0",
                            "voltage": 12.587,
                            "time": "2015-06-21 09:35:05",
                            "lat": "-35.3632617",
                            "alt": 5e-324,
                            "ascent": "4.94065645841e-324"
                        }
        },
        {   "aircraft":"Phantom",
            "live":false,
            "hardware_version":"Sky",
            "uid":4271
            "last_seen": null
        },
        {   "aircraft":"DJI Phantom 3 Professional",
            "live":false,
            "hardware_version":"Live Plus",
            "uid":5043
            "last_seen": null
        }],
    "flight_stats":
        {   "mission_max_ascent":21900.8096,
            "mission_max_altitude":20786.5655,
            "mission_max_speed":2089.792573,
            "mission_max_distance":0.0007021319588249739
        }
}
                

mission_max_ascent in meters
mission_max_altitude in meters
mission_max_speed in cm/s
mission_max_distance in earth radius units (1 = 3960 mile)

api/oauth2/1/account/info/%USER_ID%/

DESCRIPTION

Returns user account info for a specific user ID. Limited only to users who approved use of this app as well. The output will be the same as the above, but allows the retrieval of account information for users who are not using the app at the time.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/account/info/%USER_ID%/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/account/info/2654/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

api/oauth2/1/account/info-extended/%USER_ID%/

DESCRIPTION

Returns user account extended info for a specific user ID. Limited only to users who approved use of this app as well. The output will be the same as account/info-extended/, but allows the retrieval of account information for specific user.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/account/info-extended/%USER_ID%/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/account/info-extended/2654/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

api/oauth2/1/users/

DESCRIPTION

Provides a list of all users using this app, with basic details about each user who the developer has permission from.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/users/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/users/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"
[
    {   "username":"don.clapton",
        "first_name":"Don",
        "last_name":"claptopn",
        "display_name":"Don Clapton",
        "uid":34298,
        "email":"",
        "profile_url":"http://www.flytrex.com/don.clapton/"
    },
    {
        "username":"jasonperr32",
        "first_name":"Jason",
        "last_name":"Perr",
        "display_name":"Jason Perr",
        "uid":29473,
        "email":"jasonperr@gmail.com",
        "profile_url":"http://www.flytrex.com/jasonperr32/"
    },
    {
        "username":"fsesma",
        "first_name":"Frank",
        "last_name":"Sesma",
        "display_name":"Frank S",
        "uid":56432,
        "email":"fsesma@gmail.com",
        "profile_url":"http://www.flytrex.com/fsesma"
    }
]
                

api/oauth2/1/users-extended/

DESCRIPTION

Provides a list of all users using this app, with extended details about each user who the developer has permission from.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/users-extended/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/users-extended/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

[
    {   "username":"don.clapton",
        "first_name":"Don",
        "last_name":"claptopn",
        "display_name":"Don Clapton",
        "uid":34298,
        "email":"",
        "live": false,
        "profile_url":"http://www.flytrex.com/don.clapton/"
        "live_devices": [
            {   "aircraft":"Sky",
                "live":false,
                "hardware_version":"Sky",
                "uid":3270,
                "last_seen": {  "temperature": 26,
                                "flight_mode": 1,
                                "long": "149.1652248",
                                "ground_speed": "0",
                                "voltage": 12.587,
                                "time": "2015-06-21 09:35:05",
                                "lat": "-35.3632617",
                                "alt": 5e-324,
                                "ascent": "4.94065645841e-324"
                            }
            },
            {   "aircraft":"Phantom",
                "live":false,
                "hardware_version":"Sky",
                "uid":4271,
                "last_seen": null
            },
            {   "aircraft":"DJI Phantom 3 Professional",
                "live":false,
                "hardware_version":"Live Plus",
                "uid":5043,
                "last_seen": null
            }],
    },
    {
        "username":"jasonperr32",
        "first_name":"Jason",
        "last_name":"Perr",
        "display_name":"Jason Perr",
        "uid":29473,
        "email":"jasonperr@gmail.com",
        "profile_url":"http://www.flytrex.com/jasonperr32/",
        "live": true,
        "live_devices": [
            {   "aircraft": null,
                "live": true,
                "hardware_version": "Live Plus",
                "uid": 5127,
                "last_seen": null
            }
    },
    {
        "username":"fsesma",
        "first_name":"Frank",
        "last_name":"Sesma",
        "display_name":"Frank S",
        "uid":56432,
        "email":"fsesma@gmail.com",
        "profile_url":"http://www.flytrex.com/fsesma",
        "live": false
    }
]
                

api/oauth2/1/live/user/%USER_ID%/

DESCRIPTION

Opens a SSE connection stream to live flight data based on user ID. With this option, you have the ability to subscribe concurrently to multiple Live devices attached to the user ID. If the user has multiple Live devices configured to the account, the server will select the one currently live - if such is available.

If user has multiple Live devices configured and more than one Live device is currently active, the server will choose one of the active Live devices randomly (unexpected behavior). If none of the devices are active, the server will select one randomly as well.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/live/user/%USER_ID%/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/live/user/2654/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

api/oauth2/1/live/device/%DEVICE_ID%/

DESCRIPTION

Opens a SSE connection stream to live flight data based on device ID. This allows you to subscribe to live flight data from specific Live device. The device will receive data every 1 to 4 seconds, depending on the aircraft the pilot is using.

URL STRUCTURE

http://www.flytrex.com/api/oauth2/1/live/device/%DEVICE_ID%/

SAMPLE cURL REQUEST

curl https://www.flytrex.com/api/oauth2/1/live/device/FL3SG64I7Q0F5JS/ -H "Authorization: token t8Eb60qkFrUGqSa7a3qE6uIkOb6Uw2"

SSE Messaging Structure

Use the links in points #5 or #6 to subscribe to the SSE stream. Once subscribed, the server will send to your app notifications in addition to details about the current flight. Each message will consist of an event identified and JSON structure, including data about the drone status.

msg_overlay

DESCRIPTION

Includes status update, where you have the option to conditionally show status to users. This will include a no-flight message status, if the current device isn’t active. The message is sent repeatedly every few seconds.

event: msg_overlay
data: {"msg": "No live flight at the moment"}
                

mission_started

DESCRIPTION

Indicates a new flight has started. Data includes a permalink to the new mission page on Flytrex. This message is sent once for each mission.

event: mission_started
data: {"permalink": "T2OyK2tj"}
                

init_mission_location

DESCRIPTION

Sent following the start of a new mission, including the mission location takeoff details. If subscribing to an active mission after it already started you will receive this message at the beginning of your subscription. Thus, you can rely on receiving this message each time you subscribe to an active mission, or one that has just begun. This message is received once for each flight mission.

event: init_mission_location
data: {
    "city": "Near Wallingford",
    "gps_heading": 90.0",
    "country": "United Kingdom",
    "init_lat": "51.5730893",
    "init_long": "-1.1335975",
    "compass_heading": null,
    "state": "",
    "zoom_factor": 20,
    "address": "28, Oxfordshire OX86 4DQ, UK"
}
                

data

DESCRIPTION

Includes information about the current live flight, and is sent periodically. The message rate sent will change depending on the aircraft/flight controller that is connected to the Live device, and can include flight information between 1 time/sec to 4 times/sec.

When subscribing to an active flight, the ‘path’ param will include full latitude/longitude values for the entire flight, until the current time. Messages following this will include only the path delta from the previous data message received.

event: data
data: {
    "distance": "0|meter",
    "gps_heading": 90.0,
    "home_distance": "0|meter",
    "gps_fix": "3D",
    "compass_heading": null,
    "sat_count": 8,
    "voltage": "12.09",
    "flight_mode": null,
    "path": [
                ["51.5730893", "-1.1335975"],
                ["51.5730893", "-1.1335975"],
                ["51.5730892", "-1.1335975"],
                ["51.5730891", "-1.1335975"],
                ["51.573089", "-1.1335975"],
                ["51.573089", "-1.1335976"],
                ["51.5730888", "-1.1335977"],
                ["51.5730887", "-1.1335977"]
            ],
    "ascent": "-0|meter",
    "flight_time": "00:02|mins",
    "speed": "0.07|km/h"
}
                

clear_existing_mission_display

DESCRIPTION

Sent to indicate that the current mission has ended. Used to clear the display.

event: clear_existing_mission_display
data: {}