X

Getting Started

API Introduction

The Airdata API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The Airdata API is available for Enterprise subscribers. This documentation was just launched, and additional API calls will be documented here shortly.
BASE URL
COPY EXAMPLE
https://api.airdata.com

API Terms and Restrictions

Your use of the API is subject to this written documentation and usage guidelines made available by Airdata concerning its API, which may be updated from time to time. Without limiting the foregoing, you may not directly or indirectly:
  • sell, resell, lease, or otherwise make available the API or its access credentials to the API to any third party;
  • attempt to defeat any security mechanism or encryption on the API;
  • decompile, deconstruct, or attempt to derive the source code of the API or the underlying systems with which API interacts;
  • use the API to develop any competing service or offering; or
  • use the API other than as expressly authorized in the API Documentation.
Your use of the API is also subject to the Airdata Terms Of Use and Privacy Policy.

Authentication

The Airdata API uses API keys to authenticate requests. Please contact us to obtain your key. API keys are available to Enterprise subscribers. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. In most use cases, you do not need to provide a password (use an empty password). However, certain API applications will also get App Key from Airdata. In this case, the App Key will be used as the password. All API requests must be made over HTTPS, and each API request must include the API key. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Programmatically

To send API key credentials using code, add "Authorization" Header, and include a base64 encoded string of "API_KEY:" (with colon at the end). For example, if the API key is "ad_123456" then use base64 encode of "ad_123456:", and send the header: 
Authorization: Basic YWRfMTIzNDU2Og==
AUTHENTICATED REQUEST
COPY EXAMPLE
Normal use:            $ curl https://api.airdata.com/version \            -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx:                        # The colon(:) at the end prevents curl from asking for password.             If also using an App Key:            $ curl https://api.airdata.com/version \            -u prefix_EXAMPLE_KEY_ABCxxxxxxx:APP_KEY_EXAMPLE_ABCxxxxxxx                        

Accounts

The Accounts API is used to obtain information about sub-accounts (if enabled on your Airdata login).

List Sub Accounts API Keys

This API call is useful if the following two requirements are met:
  1. You have access to MANAGE -> ACCOUNTS in the Airdata UI
  2. You received an Application API Key (
    app_key
    ) from Airdata
Use this API to obtain the list of API Keys to access the data per each of your sub-accounts. Once you obtained the API Key per each sub-account, use it along with your Application API Key to access the data in each sub-account. These are special keys, and can only be used with your Application Key.
Return Values Description
email The email address of the sub-account.
company The company name, as entered by the sub-account admin, in their My Account -> Business Info page.
title The title which was given to this sub-account by the super-admin (this is not visible to the sub-account).
api_key The API key to use, used along with your Application API Key (
app_key
), to access data for that sub-account.
upload_token The auto upload token for the sub-account main email address. This can be used as the default auto upload token.

If you are trying to upload a flight using the Flight Upload API, and you only know the email address of the pilot but not the upload token, you can:
  1. Use the Upload Token API call to try to get the auto upload token for that email address
  2. If the email address is not found (for example, if a pilot with that email address was not added yet to that sub-account), as a fallback, upload using the upload token you received here. This will upload the flight to the primary email of this sub-account, so the flight is not lost.


Important: Do not share these API keys (
api_key
), or your Application Key (
app_key
), with sub-accounts. Sub-accounts may obtain their own API Keys from Airdata to use directly with only their account.

Programmatically

To send API and Application keys using code, add "Authorization" Header, and include a base64 encoded string of "API_KEY:APPLICATION_KEY". For example, if the API key is "ad_7890", and the Application key is "abcde", then use base64 encode of "ad_7890:abcde", and send the header: 
Authorization: Basic YWRfNzg5MDphYmNkZQ==
HTTP GET
COPY EXAMPLE
https://api.airdata.com/accounts/keys
Example:
curl -u prefix_EXAMPLE_KEY_ABCxxxxxxx:APP_KEY_EXAMPLE_ABCxxxxxxx       https://api.airdata.com/accounts/keys
HTTP Response
COPY CONTENT
{   "object": "list",   "results": 4,   "data": [     {       "email": "usa@airdata.com",       "company": "Airdata",       "title": "USA",       "api_key": "air_OTc3MTU9Nzc5NjY2MTY0MTYxDDg1NjI",       "upload_token": "HD11ABCD11"     },     {       "email": "europe@airdata.com",       "company": "Airdata",       "title": "European Office",       "api_key": "air_NTExMTd5Nzc5NjY5MAY1NTQxNDg23jc",       "upload_token": "HD22ABCD22"     },     {       "email": "australia@airdata.com",       "company": "Airdata",       "title": "Australian Office",       "api_key": "air_Mj4zMTU5dzc5NjY5MTaxMTkxNTQ8MzY",       "upload_token": "HD33ABCD33"     },     {       "email": "japan@airdata.com",       "company": "Airdata",       "title": "Japanese Office",       "api_key": "air_NjMaMTU5Nzc5NjY5MT22MDMxdDg7Mzc",       "upload_token": "HD44ABCD44"     }   ] }

Flights

Flights API is used to get flights list with details. The API can be used to get recent flights, or search for specific flights based on certain criteria.

List Flights

List Flights API allows you to search for flights. The API will return a list of flights, and it accepts optional search parameters, like flight time range, address, pilot, associated equipment (drone or battery), etc.
All parameters are optional, and are passed to the API as URL query strings:
Parameters Description
detail_level The amount of information to include in the response: 
  • basic
    for basic information 
  • comprehensive
    for extended information
Example: 
detail_level=comprehensive
address Address as a string value. For example: 
address=4364+Town+Center+Blvd+,El+Dorado+Hills+,CA
latitude Search Latitude. Example: 
latitude=38.650610
longitude Search Longitude. Example: 
longitude=-121.065507
radius An integer that represent the search area radius in miles or kilometers, depending on the user unit configuration.
Used with either address or latitude & longitude.
Example: 
radius=1
start Formatted date - show flights that started after this date. Flight time is searched by local flight time.
Example: 
start=2019-05-01+00:00:00
end show flights that started before this date.
Example: 
end=2019-05-01+00:00:00
drone_ids Comma separated string of drone IDs that you want to search on. Only flights done with these drones will be listed. See the Drone List API on how to find a specific ID.
Example: 
drone_ids=gIFo93ljadjcmsfj,fifmxmq8954smaA
battery_ids Comma separated string of battery IDs that you want to search on. Only flights done with these batteries will be listed. See the Battery List API on how to find a specific ID.
Example: 
battery_ids=Mxx8skao3Acd,49Aoxkmtuzaw
pilot_ids Comma separated string of pilot IDs (similar to drone_ids/battery_ids above).
role_ids Comma separated string of which roles to filter by, and works with the pilot_ids above. The available options are:
  • Pilot-in-Command
  • Mission+Commander
  • Pilot-at-Controls
  • Sensor+Operator
  • Visual+Observer
  • Instructor
For example, find all flights where a certain pilot was a visual observer or an instructor: 
pilot_ids=pil_kmL93qlvdax&role_ids=Visual+Observer,Instructor
only_without_checklist The parameter accept 0 or 1.

Specify 1 to only get flights without an answered checklist.
limit The argument accept integer value that represent the maximum limit of flights that should return.
Default: 30
Maximum: 100
offset Retrieve flights from a certain offset. For example, for page 2, use: 
offset=100&limit=100
HTTP GET
COPY EXAMPLE
https://api.airdata.com/flights?[Search query string]
Example:
curl -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx:       https://api.airdata.com/flights?longitude=-121.065507         &latitude=38.650610         &radius=5         &start=2019-05-01+00:00:00         &end=2020-07-31+23:59:59         &drone_ids=mEeqIEkUGxxxxxx,eVJ9IEkUxxxxxxx         &detail_level=comprehensive         &limit=2
HTTP Response
COPY CONTENT
{   "object": "list",   "results": 2,   "moreResultsAvailable": true,   "data": [     {       "id": "0b9da5de65289exxxxxxxxxxxxxxxxxx",       "object": "flight",       "time": "2020-07-19 11:10:24",       "epoch": "1592xxxxxx",       "title": "July 19th, 2020 11:10:24AM",       "address": " 4364 Town Center Blvd, El Dorado Hills, CA 95762, USA",       "displayLink": "https://app.airdata.com/share_embed/HDCVAKVxxxxxxxxxxxxxxxxxxxxxxx",       "csvLink": "https://app.airdata.com/csv?flight=HDCVAKVxxxxxxxxxxxxxxxxxxxxxxx",       "kmlLink": "https://app.airdata.com/kml?flight=HDCVAKVxxxxxxxxxxxxxxxxxxxxxxx&maps=1&pointer=23&default_color=ff00ffff&default_width=2&color_width=3&o=0",       "gpxLink": "https://app.airdata.com/gpx?flight=HDCVAKVxxxxxxxxxxxxxxxxxxxxxxx&default_color=ff00ffff&default_width=2&color_width=3",       "originalLink": "https://app.airdata.com/original?flight=HDCVAKVxxxxxxxxxxxxxxxxxxxxxxx",       "group": {         "id": "gro_mEM9IExxxxxxxxx",         "name": "JulyTripGroup"       },       "participants": {         "object": "list",         "data": [           {             "id": "pil_mLedIExxxxxxxxx",             "object": "participant",             "role": "Pilot-in-Command",             "name": "John Smith"           },           {             "id": "pil_YEplI2xxxxxxxxx",             "object": "participant",             "role": "Visual Observer",             "name": "Dave Cohen"           }         ]       },       "flightApp": {         "name": "DJI GO",         "version": "4.3.32"       },       "distance": {         "max": "612.5",         "unit": "Feet"       },       "altitude": {         "max": "300.5",         "unit": "Feet"       },       "speed": {         "max": "8.94",         "unit": "Miles Per Hour"       },       "temperature": {         "max": "88.5",         "unit": "Fahrenheit"       },       "drone": {         "id": "mEeqIExxxxxxxxx",         "name": "My Inspire2",         "serial": "095XE16xxxxxxx",         "type": "Inspire 2"       },       "batteries": {         "object": "list",         "data": [           {             "id": "eQaVIEkxxxxxxxx",             "name": "Bat-TB55-3xxxxx",             "serial": "09UAExxxxxxx"           },           {             "id": "YQkUIEIxxxxxxxx",             "name": "Bat-TB55-4xxxxx",             "serial": "09UAExxxxxxx"           }         ]       },       "batteryPercent": {         "takeOff": "94",         "landing": "53"       },       "duration": {         "airDuration": "317.9",         "logDuration": "319.92"       },       "takeOffLatitude": "38.xxxxxxxxxx",       "takeOffLongitude": "-120.xxxxxxxxxx"     },     {       "id": "37aff8414249ae48xxxxxxxxxxxxxxxx",       "object": "flight",       "time": "2020-06-18 16:54:45",       "epoch": "15925xxxxx",       "title": "June 18th, 2020 04:54:45PM",       "address": " 4364 Town Center Blvd, El Dorado Hills, CA 95762, USA",       "displayLink": "https://app.airdata.com/share_embed/HDCgVSVDQxNntxxxxxxxxxxxxxxxxx",       "csvLink": "https://app.airdata.com/csv?flight=HDCgVSVDQxNntxxxxxxxxxxxxxxxxx",       "kmlLink": "https://app.airdata.com/kml?flight=HDCgVSVDQxNntxxxxxxxxxxxxxxxxx&maps=1&pointer=23&default_color=ff00ffff&default_width=2&color_width=3&o=0",       "gpxLink": "https://app.airdata.com/gpx?flight=HDCgVSVDQxNntxxxxxxxxxxxxxxxxx&default_color=ff00ffff&default_width=2&color_width=3",       "originalLink": "https://app.airdata.com/original?flight=HDCgVSVDQxNntxxxxxxxxxxxxxxxxx",       "group": {         "id": "gro_mEod9xxxxxxxxx",         "name": "JuneInspections"       },       "participants": {         "object": "list",         "data": [           {             "id": "pil_mLedIEkxxxxxxxx",             "object": "participant",             "role": "Pilot-in-Command",             "name": "John Davis"           }         ]       },       "flightApp": {         "name": "DJI Pilot",         "version": "1.8.0"       },       "distance": {         "max": "2198.01",         "unit": "Feet"       },       "altitude": {         "max": "121.1",         "unit": "Feet"       },       "speed": {         "max": "13.96",         "unit": "Miles Per Hour"       },       "temperature": {         "max": "110.5",         "unit": "Fahrenheit"       },       "drone": {         "id": "miJbIExxxxxxxxx",         "name": "MyPro2",         "serial": "163DG6Jxxxxxxx",         "type": "Mavic 2 Pro"       },       "batteries": {         "object": "list",         "data": [           {             "id": "eUIfIEkxxxxxxxx",             "name": "Bat-Mavic2-3xxxxx",             "serial": "0P2AGxxxxxxxxx"           }         ]       },       "batteryPercent": {         "takeOff": "100",         "landing": "17"       },       "duration": {         "airDuration": "1520.2",         "logDuration": "1524.1"       },       "takeOffLatitude": "38.xxxxxxxxxx",       "takeOffLongitude": "-120.xxxxxxxxxx"     }   } }

Flights: Groups

Use the Flight Groups API to get groups and flights inside each group.

List Flight Groups

The API will list all flight groups, and it accepts optional sort parameters.
All parameters are optional, and are passed to the API as URL query strings:
Parameter Description
sort_by 
  • title
    sort by group title (group name) 
  • created
    sort by the time the group was created
    Example: 
    sort_by=title
    		•
    sort_dir 
  • asc
    Ascending 
  • desc
    Descending
    Example: 
    sort_by=created&sort_dir=desc
    		•
    HTTP GET
    COPY EXAMPLE
    https://api.airdata.com/flightgroups?[Search query string]
    Example:
    curl -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx:   https://api.airdata.com/flightgroups?sort_by=title   &sort_dir=asc
    HTTP Response
    COPY CONTENT
    {   "object": "list",   "results": 26,   "moreResultsAvailable": false,   "data": [     {       "id": "grMTU5NDA1Njxxxxxxxxxx",       "title": "June Inspections",       "notes": "All inspection flights done in June",       "created": "2020-07-06 10:23:42",       "flights": {         "object": "list",         "data": [           {             "id": "ef8cd210e82exxxxxxx",             "object": "flight"           },           {             "id": "bc0026c004a7xxxxxxx",             "object": "flight"           },           {             "id": "124f95219306xxxxxxx",             "object": "flight"           },           {             "id": "547f966cce1cxxxxxxx",             "object": "flight"           },           {             "id": "819a35bdbb4dxxxxxxx",             "object": "flight"           }         ]       }     },     {       "id": "grMTU3OTIyMxxxxxxxxxx",       "title": "Training",       "notes": "All of our trianing flights",       "created": "2020-06-16 16:44:24",       "flights": {         "object": "list",         "data": [           {             "id": "82a115cb7b95xxxxxx",             "object": "flight"           },           {             "id": "bf32ae602afaxxxxxx",             "object": "flight"           },           {             "id": "a928e0a90519xxxxxx",             "object": "flight"           }         ]       }     },     {...},     {...}...   ] }

    Get Flight Group Details

    Get details of a specific flight group. To get specific group information, add the group ID to the URL: 
    https://api.airdata.com/flightgroup/grXXXXXXXXXXXX

    Parameter Description
    <group id> 
    /grXXXXXXXXXXXX
    Replace with group id
    Example: 
    https://api.airdata.com/flightgroup/gr04xjke29vAx
    HTTP GET
    COPY EXAMPLE
    https://api.airdata.com/flightgroup/<group_id>
    Example:
    curl -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx:   https://api.airdata.com/flightgroup/gr04xjke29vAx
    HTTP Response
    COPY CONTENT
    {   "id": "grMTU5NDA1Njxxxxxxxxxx",   "title": "June Inspections",   "notes": "All inspection flights done in June",   "created": "2020-07-06 10:23:42",   "flights": {     "object": "list",     "data": [       {         "id": "ef8cd210e82exxxxxxx",         "object": "flight"       },       {         "id": "bc0026c004a7xxxxxxx",         "object": "flight"       },       {         "id": "124f95219306xxxxxxx",         "object": "flight"       },       {         "id": "547f966cce1cxxxxxxx",         "object": "flight"       },       {         "id": "819a35bdbb4dxxxxxxx",         "object": "flight"       }     ]   } }

    Pilots

    API calls to retrieve pilot information.

    Upload Token

    Retrieve the auto upload token by email address.
    The auto upload token is used to upload flights to an account using the Flight Upload API, and automatically link the uploaded flights to the correct pilot.


    Parameter Description
    email The email address of the pilot
    HTTP GET
    COPY EXAMPLE
    https://api.airdata.com/pilot/uploadtoken?email=<pilot email address>
    Example:
    curl -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx:       https://api.airdata.com/pilot/uploadtoken?email=david@airdata.com
    HTTP Response
    COPY CONTENT
    HTTP Response Code: 200 OK {   "object": "Pilot",   "data": {     "email": "david@airdata.com",     "upload_token": "HD1234ABCD"   } } or HTTP Response Code: 404 Not Found {   "error": "Email Not Found" }

    Live Streaming

    List recent Live Streams

    Use this API to get the list of recent live streams.
    GET
     
    https://api.airdata.com/broadcasts/recent
    Output (Response)
     
    [     {       "isLive": 1,       "personalProfileImageSrc": "https://app.airdata.com/profile_uploads/XXXX",       "fullAddress": "4364 Town Center Blvd, El Dorado Hills, CA 95762, USA",       "pilotFullName": "David Smith",       "shareLink": "https://app.airdata.com/player?sid=XXXXX",       "shareLinkPreviewImg": "https://XXX.airdata.com/XXXX.jpg",       "lastStarted": 1663955555,       "lastStopped": 1663955666,       "latitude": 38.6XXXXX,       "longitude": -120.9XXXX    },    {       "isLive": 0,       "personalProfileImageSrc": "https://app.airdata.com/profile_uploads/XXXX",       "fullAddress": "1000 Town Center Blvd, El Dorado Hills, CA 95762, USA",       "pilotFullName": "John Johnson",       "shareLink": "https://app.airdata.com/player?sid=XXXXX",       "shareLinkPreviewImg": "https://XXX.airdata.com/XXXX.jpg",       "lastStarted": 1663944444,       "lastStopped": 1663944555,       "latitude": 38.6XXXXX,       "longitude": -120.9XXXX    } ]

    Flight Upload API

    This API provides flight apps the ability to automatically upload flight logs to Airdata. It is available for any app developer, and can be used by any user, paid or free. To learn more about the user setup experience, check out HD Sync - an app written by Airdata: https://app.airdata.com/sync-app-android While HD Sync is old and has been replaced by the newer Airdata app, the guide in this link will provide a good sense of how the auto upload process works.

    Authentication

    The upload is based on an auto upload token. Each user gets a token via the Airdata web app (Available under My Account -> Auto Upload Token) All user tokens start with "HD" and are 10 characters long, case insensitive, for example: HD12345678 During the initial configuration in your app, ask the user for their Airdata Auto Upload token. You can verify this token using the following query: https://api.airdata.com/flight_upload_auth?appkey=<your_appkey>&usertoken=<User Auto Upload Token "HD...">
    Parameters Description
    your_appkey Your 8 characters app API key, for example abcd1234. Contact dev@airdata.com to get this from Airdata. Please let us know a bit about your app and your target audience: Will this be used by your company only, or is intended for the general public?
    usertoken The HD token of the user, from Airdata, such as HD12345678
    HTTP GET
    COPY EXAMPLE
    https://api.airdata.com/flight_upload_auth?appkey=<your_appkey>&usertoken=<User Auto Upload Token "HD...">
    Example:
    curl https://api.airdata.com/flight_upload_auth?appkey=abcd1234&usertoken=HD1234abcd
    HTTP Response
    COPY CONTENT
    {     "status":"success" }

    Uploading

    The upload is done via a basic HTTPS POST call. To upload flights, use POST to https://api.airdata.com/flight_upload POST parameters:
    Parameters Description
    appkey Your 8-char app API key - you will get this from Airdata, for example abcd1234
    usertoken The HD token of the user, from Airdata, such as HD12345678
    appname Such as my_app_ios or my_app_android
    appversion Such as 1.1.3
    file The actual file to upload
    For initial testing/debugging, a basic HTML form, Android and iOS sample code is available here: https://api.airdata.com/flight-api-test To get your auto upload token for testing, register to get a free account, then visit: https://app.airdata.com/main?a=account&apage_id=auto_upload_token Return value:
    Return Values Description
    job_id When a flight log is uploaded, it enters a backend queue in Airdata.
    Optional: You may check on the progress of this job using this job ID. This is optional, and there is no requirement to do anything with this value. The upload is now complete and there is no need for any additional actions.
    HTTP POST
     
    https://api.airdata.com/flight_upload
    HTTP Response
    COPY CONTENT
    {     "status":"success",     "job_id":"job_GLgbIEkeGLYwBLeb" }

    Checking Job Status

    This is an optional call to check flight upload job status. It is normally not used when implementing auto-upload from flight apps, but primarily used in more in-depth integrations. When flights are uploaded, each flight log enters a processing queue, and a 
    job_id
    is provided in the response. This job can be completed within 20 seconds to a few minutes. This call will provide the current status of this job. GET parameters:
    Parameters Description
    job_id The job_id that was returned when a flight log was uploaded. Example: job_GLgbIEkeGLYwBLeb
    usertoken Provide the "HD..." usertoken that was used to submit the upload.

    This is needed as you can only view the status of jobs submitted with the same token.

    Alternatively, you may use your Airdata API key to authenticate this request. In that case, do not send this parameter.
    Airdata API keys are different than your Upload API app key, and are available for Enterprise subscribers.
    Return values:
    Return Values Description
    status "Pending", "Running", "Success" or "Error".
    reason If status is "Error", a "reason" field will be included.
    HTTP GET
    COPY EXAMPLE
    https://api.airdata.com/flight_job/<job_id>[?usertoken=HD...]
    Example:
    curl https://api.airdata.com/flight_job/job_GLgbIEkeGLYwBLeb?usertoken=HD1234abcd
    HTTP Response
    COPY CONTENT
    {     "object": "FlightJob",     "data": {         "jobId": "job_GLgbIEkeGLYwBLeb",         "status": "Success"     } } or {     "object": "FlightJob",     "data": {         "jobId": "job_GLgbIEkeGLYwBLeb",         "status": "Error",         "reason": "Error #8835 - Unable to detect file format"     } }















     














     
    Search Result... X