airspotbot 2.0.1

airspotbot is a Twitter bot designed to provide simple, flexible way to report interesting aircraft activity in a designated area via twitter posts. It uses Tweepy and the ADS-B exchange API. airspotbot is designed to be extremely configurable, so it can be used to monitor diverse kinds of activity.

January 2023 status: read this first!

In December 2022, Twitter suspended several accounts involved in aircraft tracking (including @elonjet and @adsbexchange). At the same time, the Twitter TOS was changed to forbid posting of "live location information", a policy change which was specifically targeted at aircraft tracking accounts. In response, I suspended my own instances of airspotbot and took the repository temporarily private in order to observe the state of aircraft tracking on Twitter and consider what the next steps should be for airspotbot.

As of January 2023 I have made the repository public again. Currently, it appears that some automated aircraft tracking accounts continue to operate on Twitter. I am not personally aware of moderation actions taken against any airspotbot-based account (but please let me know if you have been affected). However, due to the intentionally broad wording and inconsistent enforcement of the Twitter TOS (as well as Musk's personal animus against sharing public aircraft tracking data), I cannot guarantee that an account run with airspotbot will not be suspended. Therefore, please understand that use of airspotbot is at your own risk.

What does the future hold for airspotbot? After this episode, I am personally less interested in supporting Twitter with my open source work due to the platform's increased hostility to aircraft tracking activities and third party development in general. Nevertheless, I have no plans to take airspotbot private again or to remove existing Twitter support. I am exploring the possibility of adding compatibility with other platforms, including federated services such as Mastodon. Your suggestions and code contributions are welcome.

What can it do?

You can configure airspotbot to tweet multiple kinds of aircraft activity within a certain area. The list below provides some examples. See the "Configuration" section for details on how to configure airspotbot for one of these use cases. airspotbot is designed so that a single bot can be configured to fulfill multiple use cases simultaneously.

• I want to tweet when an aircraft with a specific civil registration number is active in a certain area
• I want to tweet when a military aircraft with a specific serial number (for example, see US and UK serial numbers) is active in a certain area
• I want to tweet when an aircraft with a specific unique ICAO transponder address is active in a certain area
• I want to tweet all military aircraft activity in a certain area
• I want to tweet when any aircraft with a certain type code (i.e. make and model of aircraft) is active in my area
• I want to tweet when any aircraft with a certain type code is active in my area, but only if they are military

Tweets generated for any of these use cases can be enhanced with additional information, including custom descriptions, images, reverse geocoding, and embedded screenshots of the map view from https://globe.adsbexchange.com.

Limitations

airspotbot is intended to monitor a specific area, such as an airport or city. Due to limitations of the ADS-B Exchange API, airspotbot is can only track aircraft within a circle centered on the latitude and longitude specified in the configuration file. The radius of this circle must be between 1 and 250 nautical miles.

airspotbot is only as good as the data it receives. While ADS-B Exchange is a great resource that provides a huge amount of unfiltered data, there are still gaps in coverage. There are also many military aircraft that cannot be tracked or identified using their transponders. See the ADS-B Exchange FAQ for more details.

Usage

Requirements

• Python 3.10 or later.
• Valid Twitter API key. airspotbot requires both v1.1 and v2 access. v1.1 access is only required because v2 does not currently support image upload. Once v2 has this feature, v1.1 access will no longer be required. All required API functionality is available with an "Essential" level developer account.
• Valid ADS-B Exchange API key (v2 only). An API key can be obtained through their RapidAPI endpoint
• (Optional) Chrome/Chromium web browser and a compatible version of ChromeDriver. Used to capture screenshots of globe.adsbexchange.com for inclusion in tweets.

Please operate your installation of airspotbot in accordance with all relevant API terms of service.

Setup

1. Clone this repository using git: git clone https://github.com/rouyng/airspotbot.git OR download a zip file of the repository using the green "Code" button at the top of the GitHub repository page.
2. Optional: If you would like to deploy airspotbot as a Docker container, a basic Dockerfile is included. If you choose to do this, you probably know what you are doing. Otherwise, for a regular, non-Docker installation, proceed to the next step.
3. Optional: Set up a python virtual environment, using Python 3.7 or greater. This is recommended because it prevents different installations of python packages from interfering with each other.
4. Install package requirements using pip3 install -r requirements.txt
5. Configure config/asb.config with your API keys and preferences. See details in "Configuring" section below.
6. Configure config/watchlist.csv with your desired watchlist. See details in "Configuring" section below.
7. Optional: Download and install Chrome (or Chromium) browser and the ChromeDriver executable. Please note that the ChromeDriver major version must match the browser's major version. If you are using Windows, place the ChromeDriver executable in a "webdrivers/" subdirectory within the top level airspotbot directory. For other platforms, airspotbot will look for the executable in the system path. This is all automatically configured if using the included Dockerfile.

Running

Run airspotbot with python3 -m airspotbot

Command line arguments are as follows:

$ python -m airspotbot --help
usage: airspotbot [-h] [-c [CONFIG]] [-w [WATCHLIST]] [-i [IMAGEDIR]] [--version]

A twitter bot for reporting aircraft activity in an area, using the ADS-B Exchange API. For more details, see README.md.

options:
  -h, --help            show this help message and exit
  -c [CONFIG], --config [CONFIG]
                        Optional path to config file. Defaults to ./config/asb.config
  -w [WATCHLIST], --watchlist [WATCHLIST]
                        Optional path to watchlist file. Defaults to ./config/watchlist.csv
  -i [IMAGEDIR], --imagedir [IMAGEDIR]
                        Optional path to directory of images. airspotbot will search here for image files defined in the watchlist. Defaults to ./images/
  -d, --disable-tweets  Disable tweets. Can be used for testing without Twitter API credentials.
  -v, --verbose         Print debug messages.
  -q, --quiet           Only print critical error messages, ignores -v.
  --version             show program's version number and exit

Configuration

airspotbot has two files that must be configured before use: asb.config and watchlist.csv. By default, airspotbot looks for both of these files in the config/ subdirectory. The name and path of these files can be manually set using command line flags when invoking airspotbot. See "Running" section above for details.

asb.config

This file, structured in INI format, contains various configuration options organized into four sections:

• [TWITTER]: Twitter API credentials and options related to tweet interval and format. Also includes options related to screenshots.
• [ADSB]: ADS-B Exchange API credentials, spotting location information and filters to determine which aircraft are spotted/tweeted.
• [LOCATION]: Options for configuring location descriptions and reverse geocoding of aircraft locations. Has options for manually specifying a location description or connecting to Pelias and 3geonames APIs. See "Location description" section below for more details

Additional documentation on each individual option is provided as comments in the example asb.config file included in this repository.

Location description

airspotbot has several options for representing the geographical location of spotted aircraft. The location description can be entered manually or determined via reverse geocoding. These options are configured in the [LOCATION] section of asb.config.

• location_type: enter one of the following options:
  • "manual": Use some string of text, like a place/region name. This is useful if your spotting coordinates and radius is close to a distinct landmark/area and you don't need any more granular location representation. For example, if airspotbot is set up to spot aircraft in a 1 nm radius of 51.4736, -0.4688, you might set this option to "manual" and "location_description" to "near Heathrow Airport" so the bot just reports "aircraft is near Heathrow Airport".
  • "coordinate": Tweets latitude/longitude coordinates, rounded to 4 decimal places.
  • "3geonames": Use the free reverse geocoding API provided by 3geonames to reverse-lookup nearby place and/or city names based on the lat/long reported by ADSBx. Please note this is a free service that does not require signup, however requests may be throttled depending on the API provider's resource load. airspotbot also has a hardcoded 1 sec delay between requests to this API, in order to reduce load.
  • "pelias": Use pelias geocoder to reverse-lookup nearby landmarks based on the lat/long reported by ADSBx. Useful if you need airspotbot to cover a large area, such as a city with many neighborhoods and landmarks. The "pelias_host" option must also have a valid url to access a running instance of Pelias. Please note that Pelias support is very experimental. If you encounter issues or can help test it, please let me know via Github Issues.
• location_description: If "location_type" is set to "manual", enter the text string you want to be tweeted along with the spot to identify the location (such as "near Heathrow Airport", "over Downtown Los Angeles", etc).
• pelias_host: Enter the url/port of an active Pelias instance running a reverse geocoding endpoint, such as "http://192.168.1.5:4000". Required if you are using "location_type = pelias". Find more information about Pelias here.
• pelias_port: Port for API endpoint at host
• pelias_area_layer: Contains the pelias layer name used to determine the nearest area to the spotted aircraft. "neighbourhood" is a good default, but can be changed depending on how coarse/fine you need. If empty, the description will not include an area. See the Pelias docs for information on valid layers for the reverse geocoding endpoint.
• pelias_point_layer: Contains the pelias layer name used to determine the closest point of interest to the spotted aircraft. "venue" is a good default, but can be changed depending on how coarse/fine you need. If empty, the description will not include a nearby point of interest. See the Pelias docs for information on valid layers for the reverse geocoding endpoint.

watchlist.csv

This is a CSV (comma separated value) file that contains a table of aircraft criteria used to tweet spots. It can be edited in your favorite spreadsheet program or by hand. This file is optional. If you delete watchlist.csv, airspotbot will only use rules set in asb.config.

By configuring this file, you can specify aircraft to spot by registration number, aircraft type code or ICAO hex code. Please note that setting spot_unknown, spot_mil and/or spot_interesting options to "Y" in asb.config will cause unknown, military and/or ADSBx-designated "interesting" aircraft to generate tweets regardless of what is set in watchlist.csv. If you only want to spot aircraft from the watchlist, make sure those options are set to "N".

watchlist.csv contains:

• "Key": (required) Sets the aircraft registration number, ICAO type code or ICAO hex code.
• "Type": (required) Must be one of the following values
  • "RN" for registration number/serial number
  • "TC" for ICAO type code. List of valid codes.
  • "IA" for ICAO hex address (also known as ID or hex code). These are unique 24-bit addresses assigned to each individual aircraft. See this article for more details. Please note that some military aircraft may use duplicate and/or spoofed addresses.
• "Mil Only": (optional) Set to Y or N. This column only has an effect for rows with type set to "TC". When set to Y, only military aircraft with that type code will be tweeted. This feature exists because many military aircraft show up on ADS-B Exchange with civilian type codes. For example, a UH-72 Lakota will appear with a EC45 type code (referring to the Eurocopter EC145 civilian model it is based on). If you are only interested in spotting military UH-72s but not civilian EC145 helicopters, setting "Mil only" to Y will only show those aircraft with a type code of EC45 that are flagged as military.
• "Description": (optional) if filled in this will replace the type code in the tweet's text.
• "Image": (optional) filename of image file in the images/ subdirectory to associate with this watchlist item. The specified image will be added to tweets of that watchlist item. This field is case-sensitive. Any media type accepted by Twitter is allowable (JPEG, GIF, and PNG).

Warning: The watchlist file must have all five column headers present and each row must have five columns (demarcated with four commas) even if some columns are left empty. Most watchlist-related errors are caused by missing commas.

Here is an example of a valid watchlist.csv file:

Key,Type,Mil Only,Description,Image
H60,TC,N,Sikorsky H-60,uh-60.jpg
EC45,TC,Y,UH-72 Lakota,uh72.jpg
NASA941,RN,,NASA Super Guppy,
508035,IA,,Antonov AN-225 Mriya,
P28A,TC,N,Piper PA-28,test.png
N174SY,RN,,,

TODO list

Here are some planned features/fixes. You are welcome to work on these if you are interested and able (see "Contributing" section below)

• Support geoapify.com reverse geocoding API
• Fetch aircraft photos using Planespotters.net API

Contributing

Contributions are welcome, including those from new/novice contributors. Source code contributions should be via pull requests. Bug reports and feature requests via opening issues.

If you want to suggest a specific aircraft type or registration number for @phxairspots or another airspotbot-powered account to monitor, please contact the account directly.

License

airspotbot is licensed under GNU General Public License v3.0. See LICENSE.md for details.