Flight Number Mappings - davewalker5/ADS-B-BaseStationReader GitHub Wiki

Not all flight APIs support lookup of active flights by aircraft address. To support use of these APIs while tracking with auto-lookup enabled, a mechanism is needed to map from the data that is available from the ADS-B messages to a criterion that the APIs do support for flight lookup, typically the flight number. Flight number mappings provide that mechanism.

Each flight number mapping has the following properties:

If an external API doesn't support use of aircraft address for live flight lookup but does support use of flight number, the API integration first uses the callsign from the ADS-B messages to lookup a flight number in the mapping table and then uses that flight number to perform a lookup of the flight details.

In advance of a tracking session, a CSV file of callsign-to-flight mappings is created with the following columns:

Column naming and case is important but column ordering is not. Values must be given for all required columns but those that are not required may be left blank.

Once the file has been prepared, it is loaded to the database using the lookup tool:

BaseStationReader.Lookup --import-mappings /path/to/csv/file

If a callsign is already listed in the mapping table, the mapping will be updated. Otherwise, a new mapping is created.

A tool is provided to extract flight mapping details from the arrival and departure schedule responses from the AeroDataBox API:

AeroDataBox API Documentation

The endpoint of interest is as follows:

https://aerodatabox.p.rapidapi.com/flights/airports/iata/<iata>/<from>/<to>
2025-10-07T06:00/2025-10-07T18:00?withLeg=false&direction=both&withCancelled=true&withCodeshared=true&withCargo=true&withPrivate=false&withLocation=false&codeType=iata

Where <iata> is the 3-letter IATA code for the airport and <from> and <to> provide start and end date and time in YYYY-MM-DDTHH:MM format. In addtion, the following query string parameters are advisable:

For example, to retrieve the data for Stansted airport in the UK on 7th October 2025, the full URL would be:

https://aerodatabox.p.rapidapi.com/flights/airports/iata/STN/2025-10-07T06:00/2025-10-07T18:00?withLeg=false&direction=both&withCancelled=true&withCodeshared=true&withCargo=true&withPrivate=false&withLocation=false&codeType=iata

The key parts of the response look like this:

{
	"departures": [
        {
            "movement": {
                "airport": {
                    "icao": "GCFV",
                    "iata": "FUE",
                    "name": "Fuerteventura Island",
                },
            },
            "number": "LS 1631",
            "callSign": "EXS79WA",
            "airline": {
                "name": "Jet2",
                "iata": "LS",
                "icao": "EXS"
            }
        }
    ],
    "arrivals": [
    ]
}

For each airport of interest, use the Lookup Tool (see below) or a suitable REST API tool (curl, Insomina, Postman) to query the API for schedule information and store the JSON response. Then, use the "create-flight-mapping.csv.py" Python script to generate a CSV file from the responses:

python3 create-flight-mapping-csv.py -i /path/to/folder/containing/json/response/files -o /path/to/csv/file

The script extracts flight details from the departures and arrivals lists in each JSON response file, filters out those that can't be used (missing callsign or flight number) and writes the results to the specified CSV file.

Once the script completes, load the CSV file into the database per the above instructions.

The lookup tool provides options to request and store schedule information from the AeroDataBox API:

BaseStationReader.LookupTool --export-schedule <iata|file-name> <output-folder>
BaseStationReader.LookupTool --export-schedule <iata|file-name> <from> <to>  <output-folder>

The first argument is either a 3-letter airport IATA code or the path to a file containing a list of codes, one per line, in which case the application will download the schedule for each in turn.

The first form of the command constructs a time-window for today, using the ScheduleStartTime and ScheduleEndTime keys in the application settings to supply the times, requests the scheduling information and stores the resulting JSON in a file in the specified output folder, named as follows, where the date is derived from the start of the time-window:

YYYY-MM-DD-<iata>.json

The seconde form uses the data range specified by the user and emits the schedule to a file in the output folder named as per the first form of the command. Date/time can be specified in any valid form but it's strongly recommended that, to avoid any ambiguity, the dates be double-quoted and the following form used:

YYYY-MMM-DD HH:MM

Where "MMM" is the three-letter month abbreviation and HH is the hour expressed using the 24-hour clock. For example:

2025-Oct-10 16:17

The fourth form is similar to the third but the output file name is specified.