Traffic Alerts (Web Client)

Overview

The Traffic Alert API allows developers to provide their pilots with alerts about nearby traffic - including commercial airplanes, general aviation airplanes, helicopters, and some unmanned aircraft. The traffic feed is a combination of several highly reliables sources used by the airline industry. The Traffic Alert API automatically filters to alert the operator of only traffic that is low-altitude and near the current flight path.

Requirements

The Traffic Alert API requires a few other AirMap services in order to function. If you are not familiar with these tools, check out the respective guides before proceeding:

  1. Authentication: See the Authentication Module for an easy JS implementation or SSO Authentication for an API login.

  2. Flight API: You must create a flight prior to using the Traffic Alert API (since the Traffic Alert API needs to know where to filter traffic for your flight). See Creating and Viewing Flights

  3. MQTT Client Library (External): The Traffic Alert API passes traffic over MQTT, a lightweight, highly efficient messaging protocol. MQTT has been implemented in many different languages, including C/C++, Java, JavaScript, Python, Lua, and others. The examples in this guide use JavaScript and the popular Paho JavaScript Client

Setup

Create a new HTML page and include an MQTT Client Library--Paho in this example.

<!DOCTYPE html>
<html lang="en">

<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/paho-mqtt/1.0.1/mqttws31.min.js" type="text/javascript"></script>
    <style>

    </style>
</head>

<body>

    <script>


    </script>
</body>

</html>

Next, you will need to add in authentication and create a flight before listening for traffic. Choose an arbitrary flight location near an airport for this for this example:

<script>

  // Full authentication not shown - see Auth Module
  // ...
  // ...
  var token = auth.getUserToken()

  // Create simple flight

  var flight_id = ""
  
  var lat = 34.0248
  var lon = -118.44267
  var buffer = 1000

  var data = {
    latitude: lat,
    longitude: lon,
    buffer: buffer
  }

  $.ajax({
    url: "https://api.airmap.com/flight/v2/point",
    headers: {
      "X-API-KEY": "<YOUR_API_KEY>",
      "Authorization": "Bearer " + auth.getUserToken(),
      "Content-Type": "application/json; charset=utf-8"
    },
    type: "post",
    data: JSON.stringify(data),
    dataType: "json",
    success: function(res) {

      flight_id = res.data.id

      console.log("Flight created: " + flight_id)

      listenTraffic()

    },
    error: function(err) {
      alert(err.name + ":" + err.message)
    }
  })
</script>

You have now successfully created a flight and can start listening for traffic--you just need to implement the listenTraffic() function. Before doing that, however, here are some key parameters for setting up an MQTT connection:

Note

Web browsers don’t support native MQTT packets and instead use a web socket implementation of the MQTT protocol at port 8884. If you are not using a web browser, please use port 8883

Host

mqtt-prod.airmap.io

Port

8884

Client ID

<UUID>

Username

<flight id>

Password

<auth usertoken>

SSL

True

Alert Topic

uav/traffic/alert/<flight id>

Situational Awareness Topic

uav/traffic/sa/<flight id>

Note that you can subscribe to two different topics. The Situational Awareness Topic provides all traffic that is near a drone flight, while the Alert Topic provides only traffic that is heading directly toward the drone flight. You may subscribe to only one, or both simultaneously.

Also note that for this web client example, the WebSockets port used to connect to the MQTT broker is 8884 (since native MQTT is not supported). However, when connecting a client using native MQTT, the correct port number is 8883.

Here is the implementation of listenTraffic that you can place at the bottom of the <script>:

function listenTraffic() {

  var client = new Paho.MQTT.Client('mqtt-prod.airmap.io', 8884, "c-mqqt-cli")

  client.onMessageArrived = onMessageArrived

  function onMessageArrived(message) {
    console.log("onMessageArrived:" + message.payloadString);
  }

  client.connect({
    onSuccess: onConnect,
    userName: flight_id,
    password: auth.getUserToken(),
    useSSL: true
  })

  function onConnect() {

    console.log("Connected")

    var topic_alert = 'uav/traffic/alert/' + flight_id

    var topic_sa = 'uav/traffic/sa/' + flight_id

    client.subscribe(topic_sa)

  }

}

Now, whenever traffic is received, it will be printed out in the console:

onMessageArrived:{"traffic":[{"id":"SAS940-1492320347-airline-0016","direction":164.50648383691384,"altitude":"13700","latitude":"34.01129","longitude":"-118.29383","recorded_time":"1492551878","ground_speed_kts":"373","true_heading":"55","properties":{"aircraft_id":"SAS940"},"timestamp":1492551892694}]}

The payloadString in the MQTT message contains a JSON string that is an array of traffic objects (i.e. "traffic": [t1,t2,...]). Here are the parameters for each traffic object:

Parameter
Description

id

unique id of traffic

direction

Direction of aircraft relative to UAS flight (client)

altitude

Altitude of aircraft in feet

latitude

Latitude in decimal degrees

longitude

Longitude in decimal degrees

recorded_time

UTC time aircraft was recorded

ground_speed_kts

Ground speed in knots

true_heading

True heading of aircraft in degrees

properties.aircraft_id

Aircraft tail number

timestamp

UTC time aircraft alert sent out