Managing Flights

Submitting a Flight Plan

In order to create a flight on the AirMap platform, your application must first create a Flight Plan. Once a flight plan has been created and updated as desired, you may then submit the plan to create a flight:

## Submit Flight
curl -X "POST" "https://api.airmap.com/flight/v2/plan/{FLIGHT PLAN ID}/submit" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer <AUTH_TOKEN>" \
     -H "X-API-Key: <API_KEY>" \
     -d $'{
  "public": true
}'

## The response includes the id of the created flight as well as details from the original flight plan:

{
    'data': {
        'aircraft_id': 'aircraft|oWng4XPHg0aW9Dfl58zLLCl7R9ye',
        'buffer': 1,
        'end_time': '2020-03-21T03:19:12.017Z',
        'flight_description': 'a description',
        'flight_features': {
            'accept-language': 'en',
            'flight_max_altitude_agl': 60.96,
            'flight_min_altitude_agl': 0,
            'max_linear_extent': 198.03384423925525
        },
        'flight_id': 'flight|YAen7val9maJNc3QR3P08KJRn9HgYePzRXvb2WOf0pox97k8lLv',
        'geometry': {
            'coordinates': [
                [[-116.972714960575, 33.0800106510741],
                 [-116.970891058445, 33.0800106510741],
                 [-116.970891058445, 33.0811051512369],
                 [-116.972714960575, 33.0811051512369],
                 [-116.972714960575, 33.0800106510741]]],
            'type': 'Polygon'
        },
        'id': 'flight_plan|J8KpY6ax4X7xLS75O4GLdEkE8IOA6pGZz0Ng4zcoBPWNZYG9xBO',
        'max_altitude_agl': 60.96,
        'min_altitude_agl': 0,
        'pilot_id': 'kc|0ca2d34c-1bf6-4204-9f3a-e248cce4ddcb',
        'rulesets': ['usa_part_107'],
        'start_time': '2020-03-21T02:49:12.017Z',
        'takeoff_latitude': 66.50772,
        'takeoff_longitude': 137.599952},
    'status': 'success'
}

AirMap.submitFlightPlan(<#T##flightPlanId: String##String#>) { result in
    switch result {
    case .error(let error):
    // Handle error case
    case .value(let flightPlan):
        // Handle success case
    }
}

AirMap.submitFlightPlan(flightPlanId, new AirMapCallback<AirMapFlightPlan>() {
    @Override
    protected void onSuccess(AirMapFlightPlan flightPlan) {
        AirMapLog.d(TAG, "Flight id: " + flightPlan.getFlightId());
    }

    @Override
    protected void onError(AirMapException e) {
        // Handle error case
    }
});

You are now ready to take flight with your aircraft!

Ending a Flight

After the aircraft has landed, your application should end the flight so the platform knows the aircraft is no longer flying:

curl -X "POST" "https://api.airmap.com/flight/v2/{FLIGHT_ID}/end" \
    -H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
    -H "X-API-Key: {YOUR API KEY}"

AirMap.endFlight(by: <#T##Flight Id#>) { result in
    switch result {
        case .error(let error):
    // Handle error case
  }
}

// only call end if the flight is active
AirMap.endFlight(flightId, new AirMapCallback<AirMapFlight>() {
    @Override
    public void onSuccess(AirMapFlight response) {
        // Handle success (remove from map, disable traffic alerts, etc)
    }

    @Override
    public void onError(AirMapException e) {
        // Handle error
    }
});

var request = require('superagent');

request.post('https://api.airmap.com/flight/v2/{FLIGHT_ID}/end')
  .set('Authorization', 'Bearer {YOUR ACCESS TOKEN}')
  .set('X-API-Key', '{YOUR API KEY}')
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log('Oh no! error');
    } else {
      console.log('yay got ' + JSON.stringify(res.body));
    }
  });

import requests

def send_request():
    try:
        response = requests.post(
            url="https://api.airmap.com/flight/v2/{FLIGHT_ID}/end",
            headers={
                "Authorization": "Bearer {YOUR ACCESS TOKEN}",
                "X-API-Key": "{YOUR API KEY}",
            },
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

require 'net/http'
require 'net/https'

def send_request
  begin
    uri = URI('https://api.airmap.com/flight/v2/{FLIGHT_ID}/end')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    # Create Request
    req =  Net::HTTP::Post.new(uri)
    # Add headers
    req.add_field "Authorization", "Bearer {YOUR ACCESS TOKEN}"
    # Add headers
    req.add_field "X-API-Key", "{YOUR API KEY}"

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

Viewing Flights

Your application can also request already created flights for reference. You have the option to retrieve a specific flight or retrieve a list of flights.

View Single Flight

To get a singe flight, provide the id of the flight to the Flight API:

curl -X "GET" "https://api.airmap.com/flight/v2/{FLIGHT ID}?enhance=true" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
    -H "X-API-Key: {YOUR API KEY}"

## The response details the specifics of the flight:

{
    "status": "success",
    "data": {
    "id": "flight|oNm5Ky4JGaqagHdgAv7YEK8QKIwxDD3pvPdXB4IakLYEMKYmRAa",
    "pilot_id": "kc|0ca2d34c-1bf6-4204-9f3a-e248cce4ddcb",
    "aircraft_id": "aircraft|oWng4XPHg0aW9Dfl58zLLCl7R9ye",
    "latitude": 74.391695,
    "longitude": 77.711908,
    "buffer": 1,
    "geometry": {
        "type": "Polygon",
        "coordinates": [
        [
            [-116.972714960575, 33.0800106510741],
            [-116.970891058445, 33.0800106510741],
            [-116.970891058445, 33.0811051512369],
            [-116.972714960575, 33.0811051512369],
            [-116.972714960575, 33.0800106510741]
        ]
        ]
    },
    "start_time": "2020-03-11T17:09:56.000Z",
    "end_time": "2020-03-11T17:05:01.430Z",
    "created_at": "2020-03-11T17:04:59.000Z",
    "max_altitude": 60.959999084472656,
    "public": true,
    "notify": true,
    "flight_plan_id": "flight_plan|8mv4mMWXnloGDSOPabv30aQedRs4qZ7mAKRGkJhwOze5YGOMqbe",
    "pilot": {
        "id": "kc|0ca2d34c-1bf6-4204-9f3a-e248cce4ddcb",
        "username": "my_new_username"
    },
    "aircraft": {
        "id": "aircraft|oWng4XPHg0aW9Dfl58zLLCl7R9ye",
        "model": {
        "id": "c7ed05c7-cbe1-43a4-b2a8-500d5607e994",
        "name": "Karma",
        "manufacturer": {
            "id": "63280fbf-3c7f-47f4-9168-5763899048cd",
            "name": "GoPro"
        }
        }
    }
    }
}

AirMap.getFlight(by: <#T##Flight Id#>) { (result) in
      switch result {
      case .error(let error):
      // Handle error case
      case .value(let flight):
          // Handle success case
      }
  }

AirMap.getFlight(flightId, new AirMapCallback<AirMapFlight>() {
    @Override
    protected void onSuccess(AirMapFlight flight) {
        AirMapLog.d(TAG, "Flight : " + flight.getFlightId());
        
        // Handle success
    }

    @Override
    protected void onError(AirMapException e) {
        // Handle error
    }
});

var request = require('superagent');

request
  .get('https://api.airmap.com/flight/v2/{FLIGHT ID}')
  .set('X-API-Key', '{YOUR API KEY}')
  .query({"enhance":"true"})
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log('Oh no! error');
    } else {
      console.log('yay got ' + JSON.stringify(res.body));
    }
  });

import requests

def send_request():
    try:
        response = requests.get(
            url="https://api.airmap.com/flight/v2/{FLIGHT ID}",
            params={
                "enhance": "true",
            },
            headers={
                "X-API-Key": "{YOUR API KEY}",
            },
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

require 'net/http'
require 'net/https'

def send_request
  begin
    uri = URI('https://api.airmap.com/flight/v2/{FLIGHT ID}?enhance=true')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER


    # Create Request
    req =  Net::HTTP::Get.new(uri)
    # Add headers
    req.add_field "X-API-Key", "{YOUR API KEY}"

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

View List of Flights

You can also view a list of all of the authenticated pilot's flights by omitting the flight id in the endpoint:

curl -X "GET" "https://api.airmap.com/flight/v2/?enhance=true" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
    -H "X-API-Key: {YOUR API KEY}"

AirMap.listPublicFlights { result in
    switch result {
      case .error(let error):
      // Handle error case
      case .value(let flights):
            // Handle success case
    }
}

AirMap.getPublicFlights(new AirMapCallback<List<AirMapFlight>>() {
    @Override
    protected void onSuccess(List<AirMapFlight> flights) {
        AirMapLog.d(TAG, "Public flights: " + flights);
        // Handle success
    }

    @Override
    protected void onError(AirMapException e) {
        // Handle error
    }
});

var request = require('superagent');

request
  .get('https://api.airmap.com/flight/v2/')
  .set('X-API-Key', '{YOUR API KEY}')
  .query({"enhance":"true"})
  .end(function(err, res){
    if (err || !res.ok) {
      console.log(err);
    } else {
      console.log(res.body);
    }
  });

import requests

def send_request():
    # GET Flight
    # GET https://api.airmap.io/flight/stage/

    try:
        response = requests.get(
            url="https://api.airmap.com/flight/v2/",
            params={
                "enhance": "true",
            },
            headers={
                "X-API-Key": "{YOUR API KEY}",
            },
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

require 'net/http'
require 'net/https'

def send_request
  # GET Flight (GET )

  begin
    uri = URI('https://api.airmap.com/flight/v2/?enhance=true')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER


    # Create Request
    req =  Net::HTTP::Get.new(uri)
    # Add headers
    req.add_field "X-API-Key", "{YOUR API KEY}"

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

Finally, for HTTP requests, we can add a variety of query parameters that give us the flexibility to filter the results. (see Get Flights reference for full list). The mobile SDK's have convenience methods that accept an optional from (Date), to (Date) and limit (Int).

📘
Pro Tip
Time parameters are typically in the standard ISO 8601 format 2018-01-01T12:00:00-08:00, but you can also use the string now to designate the current server time.

## Get Active Flight
## For example, to see all currently active flights, we can add in a `start_before` and `end_after` with the current time. 

curl "https://api.airmap.com/flight/v2/?pilot_id=auth0%7C591dea1006732e54be4b875f&end_after=now&start_before=now" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer <AUTH_TOKEN>" \
     -H "X-API-Key: <API_KEY>" \
     -d $'{}'

AirMap.listPublicFlights(from: <#T##Date?#>, to: <#T##Date?#>, limit: <#T##Int?#>) { result in
 
   switch result {
        case .error(let error):
        // Handle error case
        case .value(let flights):
        // Handle success case
   }        
}

AirMap.getPublicFlights(1000, fromDate, toDate, new AirMapCallback<List<AirMapFlight>>() {
    @Override
    protected void onSuccess(List<AirMapFlight> flights) {
        AirMapLog.d(TAG, "Public flights: " + flights);
        // Handle success
    }

    @Override
    protected void onError(AirMapException e) {
        // Handle error
    }
});

Deleting a Flight

🚧
Heads up!
You should only delete a flight if the current time is before the start time and the flight will not take place. Use the /end endpoint described above when landing a flight.

If desired, you may remove a flight from the pilot's history permanently:

curl -X "POST" "https://api.airmap.com/flight/v2/{FLIGHT ID}/delete" \
    -H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
    -H "X-API-Key: {YOUR API KEY}"

AirMap.deleteFlight(<#T##flight: AirMapFlight##AirMapFlight#>) { result in
    switch result {
        case error(let error)
    }
}

AirMap.deleteFlight(flight, new AirMapCallback<Void>() {
    @Override
    protected void onSuccess(Void response) {
        // Handle success
    }

    @Override
    protected void onError(AirMapException e) {
        // Handle error
    }
});

var request = require('superagent');

request  .post('https://api.airmap.com/flight/v2/{FLIGHT ID}/delete')
  .set('Authorization', 'Bearer {YOUR ACCESS TOKEN}')
  .set('X-API-Key', '{YOUR API KEY}')
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log('Oh no! error');
    } else {
      console.log('yay got ' + JSON.stringify(res.body));
    }
  });

import requests

def send_request():
    try:
        response = requests.post(
            url="https://api.airmap.com/flight/v2/{FLIGHT ID}/delete",
            headers={
                "Authorization": "Bearer {YOUR ACCESS TOKEN}",
                "X-API-Key": "{YOUR API KEY}",
            },
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

require 'net/http'
require 'net/https'

def send_request
  begin
    uri = URI('https://api.airmap.com/flight/v2/{FLIGHT ID}/delete')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    # Create Request
    req =  Net::HTTP::Post.new(uri)
    # Add headers
    req.add_field "Authorization", "Bearer {YOUR ACCESS TOKEN}"
    # Add headers
    req.add_field "X-API-Key", "{YOUR API KEY}"

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

AirMap Developers

Managing Flights

Submitting a Flight Plan

Ending a Flight

Viewing Flights

View Single Flight

View List of Flights

📘
Pro Tip

Deleting a Flight

🚧
Heads up!

What's Next

Managing Flights

Suggested Edits are limited on API Reference Pages

Submitting a Flight Plan

Ending a Flight

Viewing Flights

View Single Flight

View List of Flights

📘Pro Tip

Deleting a Flight

🚧Heads up!

What's Next

📘
Pro Tip

🚧
Heads up!