Advisory Circular

This is a twitter bot that alerts you when aircraft fly in circles. You can see it in action at @SkyCirclesLA.


This bot is written in Clojurescript, targeting Node.

The bot uses the adsbexchange.com API to get aircraft data in realtime. It uses the Pelias front-end to OpenStreetMap and WhosOnFirst data to come up with some color description of the aircraft's location. It uses an embedded Chromium browser to take a screenshot of the aircraft on the adsbexchange.com "global radar view".

Criteria for tweeting

The bot will consider an aircraft to be "circling" if:

1. In the past 25 minutes, the sum of the aircraft's bearing changes is more than 1440 degrees. Port turns cancel out starboard turns and vice versa--there needs to be a net change of at least 1440 degrees in one direction.

2. The centroid of the last 3 minutes worth of positions must be more than 2.5 km away from all known airports.

3. The centroid must be located within the county of Los Angeles. (This is just because I don't yet have airport data outside Los Angeles County.)

4. The aircraft must, at the moment of decision, be at an altitude of 300 feet or more.

5. Once an aircraft is considered to be circling, it will be tweeted about. It won't be eligible to be considered circling/tweeted about again until it stops circling and 30 minutes pass.

There are a lot of weird flight paths that can meet criterion #1, and I kind of like it that way. For example, see https://twitter.com/lemonodor/status/1203033917483175936 (consider whether we also want to detect something like https://twitter.com/lemonodor/status/1204550831103590400).

Prerequisites to running the bot

Set up a Pelias instance containing information for the geographical area you're interested in. See https://github.com/pelias/docker and if you're lucky the projects folder will have a predefined project that covers the area you want. I run one using the los-angeles-metro project.

Get an API key for adsbexchange.com. See https://www.adsbexchange.com/data/ If you have a receiver and feed them data, they'll give you a key for free. Alternately, find another data source of realtime (or not) aircraft data and massage it into a form that the bot can work with.

Get access keys for a twitter account. Follow the instructions at botwiki.

Running the bot

Put your adsbexchange.com API key and twitter keys in secrets.yaml.

Create an initial history database:

echo '{}' > advisory-circular.db

Install node dependencies:

npm install

Compile the clojurescript:

npx shadow-cljs compile script

Run the bot:

node out/script.js --adsbx-url https://adsbexchange.com/api/aircraft/json \
                   --pelias-url http://my-pelias.local:4000/v1 \
                   --lat <lat> --lon <lon> --radius <radius>`

Specify your geographical region of interest by specifying a circle at
`<lat>`, `<lon>` with a radius of `<radius>` miles.

The bot will run once. The adsbexchange.com API only provides
instantaneous positions, so the bot will have to run many times and
collect some history before it's able to detect any circles.

while : do node out/script.js --adsbx-url https://adsbexchange.com/api/aircraft/json --pelias-url http://my-pelias.local:4000/v1 --lat --lon --radius sleep 10 done

* **Do not run the script with a large radius, or adsbexchange.com will
  ban your IP.** I use a radius of 40 miles.

* **Do not run the script more ofen than once every 10 seconds, or
  adsbexchange.com will ban your IP.**


## To do

- [ ] If we don't have neighbourhood or locality (just county), try to
      use the locality of a nearby venue. E.g. "2 miles from
      Glendale."
- [ ] Solve the issue of needing a differently sized buffer zone for
      different airports--2 miles distance from LAX is still
      practically inside the aiport. Add list with custom airport
      coords and radii? Get access to OSM polygons and compute our own
      distances?
- [ ] Add type information to tweet status, e.g. "Eurocopter AS350".
- [ ] Lookup registration info. Possible sources: FAA,
      adsbexchange.com, janky-ass basestation.sqb's that have been
      passed around for a decade.
- [ ] Find a source of aircraft images we can use.
- [ ] Use Wikipedia graph to rank landmarks? More inbound links to a
      page means it has higher significance?
- [ ] Add support for Mastodon/ActivityPub.
- [ ] Generate our own maps instead of using adsbx's? The adsbx map
      isn't always in sync with the data from the API.
- [ ] Run at global scale!