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 reliable 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:

Authentication: See the Authentication Module for an easy JS implementation or SSO Authentication for an API login.
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
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.airmap.com`
port	`8884`
clientId		Must be unique per client
userName		Ex: "flight\|abc123..."
password		JWT
ssl	True
Alert Topic	`uav/traffic/alert/<flight id>`
Situational Awareness Topic	`uav/traffic/sa/<flight id>`	Situational Awareness traffic topic does not include messages dispatched via the alert topic.

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 in the browser). 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() {

  // SOME MQTT CLIENTS require a "/mqtt" at the end of the URL
  var client = new Paho.MQTT.Client('mqtt.airmap.com', 8884, "c-mqtt-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

AirMap Developers

Traffic Alerts (Web Client)

Overview

Requirements

Setup

🚧
Note

Traffic Alerts (Web Client)

Suggested Edits are limited on API Reference Pages

Overview

Requirements

Setup

🚧Note

🚧
Note