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
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:
|
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. ProgrammaticallyTo 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== Python Sample CodeThe following Python code demonstrates a simple call to check the API version:import http.client import base64 api_key = "ad_abcde.......example......" api_key = api_key + ':' # Add a colon # Encode the API key in base64 api_key_encoded = base64.b64encode(api_key.encode()).decode("utf-8") conn = http.client.HTTPSConnection("api.airdata.com") payload = '' headers = { 'Authorization': f'Basic {api_key_encoded}' } conn.request("GET", "/version", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) |
AUTHENTICATED REQUEST
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:
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. ProgrammaticallyTo 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
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
{
"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"
}
]
}
|
Update Sub Account
Use this API to update the license date of a sub-account (if available).
|
HTTP GET
https://api.airdata.com/accounts/<account email address>
Example: curl -u prefix_EXAMPLE_KEY_ABCxxxxxxx:APP_KEY_EXAMPLE_ABCxxxxxxx -X PUT -d '{"validuntil":"2025-01-20"}' "https://api.airdata.com/accounts/johnsmith@airdata.com" HTTP Response
{
"result": "success"
}
|
Remove Sub Account
Use this API to remove/detach the sub-account from your Super Admin or reseller account.
This will convert this sub-account to a stand-alone free account.
|
HTTP GET
https://api.airdata.com/accounts/<account email address>
Example: curl -u prefix_EXAMPLE_KEY_ABCxxxxxxx:APP_KEY_EXAMPLE_ABCxxxxxxx -X DELETE "https://api.airdata.com/accounts/johnsmith@airdata.com" HTTP Response
{
"result": "success"
}
|
Equipment
API calls to retrieve equipment information. |
Drones List
Retrieve a list of drones for the account.
|
HTTP GET
https://api.airdata.com/drones
HTTP Response
[
{
"id": "a4d4eb168a814cf38670edxxxxxxxxxx",
"name": "Drone1",
"model": "Matrice 300 RTK",
"brand": "DJI",
"airworthiness": "Maintenance Due",
"operational": "Yes",
"internalSerial": "1ZNBK4K0xxxxxx",
"printedSerial": "123XXXXX",
"remoteID": "IDXXXXX",
"registration": "N/A",
"purchased": "Jul 19th, 2023",
"notes": "My notes #1"
},
{
"id": "8bc01c6b682af5c02dc49axxxxxxxxxx",
"name": "Drone2",
"model": "Air 3",
"brand": "DJI",
"airworthiness": "Good to fly",
"operational": "Yes",
"internalSerial": "1FQBC2A3xxxxxx",
"printedSerial": "456XXXXX",
"remoteID": "IDXXXXX",
"registration": "N/A",
"purchased": "Oct 18th, 2023",
"notes": "My notes #2"
}
]
|
Batteries List
Retrieve a list of batteries for the account.
|
HTTP GET
https://api.airdata.com/batteries
HTTP Response
[
{
"id": "46c57b5dd0982a0e11e58axxxxxxxxxx",
"name": "Bat-Air3-A0xxxx",
"model": "Air3",
"Type": "Air 3 Battery",
"maxCapacity": "4241 mAh",
"operational": "Yes",
"purchased": "Aug 09th, 2023",
"batteryLife": "99%",
"notes": "My notes #1",
"internalSerial": "N/A",
"printedSerial": "6NVPL6CDA0xxxx"
},
{
"id": "68100ad8c296293ac8f764xxxxxxxxxx",
"name": "Bat-TB60-A0xxxx",
"model": "TB60",
"Type": "M300 RTK Battery",
"maxCapacity": "5935 mAh",
"operational": "Yes",
"purchased": "Jun 14th, 2023",
"batteryLife": "100%",
"notes": "My notes #2",
"internalSerial": "N/A",
"printedSerial": "1Z6PHCHDA0xxxx"
}
]
|
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:
|
HTTP GET
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 &created_after=2019-06-01+00:00:00 &limit=2 HTTP Response
{
"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:
|
HTTP GET
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
{
"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
|
HTTP GET
https://api.airdata.com/flightgroup/<group_id>
Example: curl -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx: https://api.airdata.com/flightgroup/gr04xjke29vAx HTTP Response
{
"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. |
Pilots List
Retrieve a list of pilots for the account.
|
HTTP GET
https://api.airdata.com/pilots
Example: curl -u ad_EXAMPLE_KEY_Gx1vUBTxxxxxxx: https://api.airdata.com/pilots HTTP Response
HTTP Response Code: 200 OK
[
{
"id": "pil_YVJqIEkxxxxxxxx",
"name": "David Smith",
"email": "david@airdata.com",
"upload_token": "HD1234ABCD",
"color": "Transparent",
"organization": "My Org #1",
"notes": "My Notes",
"registrationNumber": "123XXXXXX"
},
{
"id": "pil_mLedIxxxxxxxxxx",
"name": "John Johnson",
"email": "john@airdata.com",
"upload_token": "HDABCD5678",
"color": "Blue",
"organization": "My Org #2",
"notes": "Abc 123",
"registrationNumber": "111XXXXXX"
}
]
|
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.
|
HTTP GET
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
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.
Please note that the return values rtmpURL and shareLinkPreviewImg may change on a daily basis. |
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/yyyy/XXXX.jpg",
"rtmpURL": "rtmp://XXX.airdata.com/yyy/XXXXXXX",
"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/yyyy/XXXX.jpg",
"rtmpURL": "rtmp://XXX.airdata.com/yyy/XXXXXXX",
"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...">
|
HTTP GET
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
{
"status":"success"
}
|
Uploading
[Updated Oct 2024]
For each file, uploading is a 2 step process:
|
Step 1: Determine the destination server
Query using a basic HTTPS POST call.
POST to https://api.airdata.com/get_upload_destination
POST parameters:
|
HTTP POST
https://api.airdata.com/get_upload_destination
HTTP Response
{
"upload_url": "https://api-us-ext.airdata.com/flight_upload"
}
|
Step 2: Uploading
The upload is done via a basic HTTPS POST call.
To upload flights, use POST to the destination server returned with the previous call. Each file may have a different destination server, so please query the destination server per each file.
POST parameters:
|
HTTP POST
https://<variable>.airdata.com/flight_upload
HTTP Response
{
"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_idis 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:
|
HTTP GET
https://api.airdata.com/flight_job/<job_id>[?usertoken=HD...]
Example: curl https://api.airdata.com/flight_job/job_GLgbIEkeGLYwBLeb?usertoken=HD1234abcd HTTP Response
{
"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"
}
}
|