Improving the navigation briefing experience

Motivation • Quick Start • Usage • Contributing

NavBrix API enables NavCraft API to work with weather forecasts and NOTAMs, from the Nav Canada weather briefing web app CFPS.

• It connects to the NavCraft API's database and updates the flight plans' weather.

• It provides departure, arrival, enroute and alternate weather and NOTAM briefings.

🌟 Motivation

NavBrix API was developed to achieve one goal:

Make the NavCraft API immune to weather changes.

NavCraft API makes the long and stressful task of flight planning, effortless. However, every time the weather changes, my flight plans break. Expecting a pilot to update the weather and NOTAM briefings and the departure, arrival and enroute weather data every time the weather changes, is unrealistic.

With NavBrix API, pilots don’t need to worry about outdated flight plan weather data.

🚀 Quick Start

The API is live. Navigate to the documentation on navbrixapi.com/docs

👨‍💻 Usage

If you use NavCraft API as the backend of your flight planning web, mobile or desktop app, you can enhance it with the NavBrix API. To call the Navbrix API endpoints, use the API’s URL, followed by the endpoint’s route. For example, to request a weather briefing for the flight with ID 352, you call:

https://navbrixapi.com/api/briefings/weather/352

In the documentation, you can find a list of the exposed endpoints, with a brief description of what they do, and detailed schemas of the request and response data structures.

The data you need to provide in the request body may be extensive, but all of it can be extracted from the NavCraft API's Get Flight endpoint's response:

https://navcraftapi.com/api/flights/{flight_id}

API Architecture

Understanding the API’s architecture will help you navigate it better. NavBrix API was written using the Express Node.js library. The backbone of the API is divided into two main parts, its database and a directory of web scrapping classes.

The Database

As shown in the conceptual model diagram below, NavBrix API extends the NavCraft API's MySQL database, to include a Weather group.

The weather group is made up of two main entities:

1. The aerodrome_weahter_report entity stores the weather reports used to get the latest departure and arrival weather. That is, it holds a list of the latest Terminal Aera Forecast (TAF) and Meteorological Terminal Aviation Routine Weather Report (METAR) weather data, at the nearest aerodromes.

2. Similarly, the enroute_weather_report holds a list of the latest METAR and Forecast Winds and Temperatures Aloft (FD) weather data, at the aerodromes closest to the center of each enroute leg.

The Web Scraper

The data provided by NavBrix API has to be reliable like lives depend on it; because they do. NAV Canada is the most reliable source when it comes to Canadian aviation publications. Unfortunately, NAV Canada has API options for businesses by data sales inquiry, but not a dedicated open API option for open source projects. Fortunately, NAV Canada does have a web tool that provides the data NavBrix API needs. The CFPS tool is live and open to the public.

Since querying a dedicated API wasn't an option, the second best option was web scrapping. NavBrix API uses a headless browser to query the CFPS web tool and scrape the weather reports and NOTAMs. The methods used to achieve this, are separated into four Javascript classes:

1. The Scrapper class uses the Node.js library Puppeteer, to run the headless browser and scrape the weather reports and NOTAMs.

2. The Processor class pre-processes the input data to the scraper and post-processes the output data, to organize it in Javascript objects.

3. The Interpreter class uses regular expressions to extract the required data from the weather reports.

4. The Cleaner class structures the extracted data in a clean format to input into the database and/or return it to the client.

🤝 Contributing

Currently looking for help to work on the following features/issues, in order of urgency:

1. Issues 🐞

If you find a bug or a feature you want to implement, please raise an issue and submit a pull request. Your contributions are greatly appreciated.

2. Testing

The first version of the NavBrix API does not have tests in place. However, The fact that the API relies on web scrapping, makes it susceptible to changes in external sources. To control this vulnerability, the API uses Typescript for strong type checking and Zod for input and output data validation. The next step to ensure a reliable behavior from the API, would be to use the Vitest library to unit test the methods of the four scraper classes.

If as part of implementing these tests, you consider refactoring the code is appropriate, your contributions are also welcome.

3. Interprete Reports 🕵️‍♂️

Aviation publications like weather reports and NOTAMs, have very specific structures. You can take advantage of this structure, to use regular expressions to extract specific information and use it to add more informative value to the briefings. A version of this is already being implemented in the Interpreter class of the API, but there's a lot of data yet to be extracted from NOTAMs and weather reports.

To work on this, you need to have a good understanding of how to use regular expressions and how to read NOTAMs and/or weather reports such us TAFs, METARs, FDs, AIRMETs and SIGMETs.

When it comes to what data to extract from the reports you can use your imagination, but here are some ideas:

• High-Level Upper Winds and Temperatures:

  FDs are divided into low and high levels. Low-level FDs report from 3000 ft ASL up to 18,000 ft ASL every 3 to 6 thousand ft. Above 18,000 ft ASL is considered IFR territory and, since NavCraft API is for VFR flight plans, the high-level FDs were not used for the first version of the API. Nonetheless, since the values for the "in-between" altitudes that are not reported are being estimated with linear regressions, extracting the high-level winds and temperatures may help with the linear regressions used to estimate the altitudes closer to the 18,000 ft limit.

• Aerodrome Weather:

  By extracting the clouds and visibility from TAFs and METARs, you can report which aerodromes are under VFR, IFR or marginal VFR conditions. This information is very handy to include in the briefings.

• AIRMETs/SIGMETs' Airspace:

  AIRMETs and SIGMETs include the coordinates of where the phenomenon is happening. Extracting these coordinates and sending them to the client, can help the client display the AIRMETs and SIGMETs in a map.

• Label NOTAMs:

  NOTAMs inform pilots about a lot of different potential hazards. By identifying keywords like obstacle, crane, fire, fuel not available, runway closed, etc, you can put labels on the NOTAMs to categorize them.

Helpful resources:

• NAV Canada's Aviation Weather Service Guide - download here

• Transport Canada Aeronautical Information Manual - download here

🛠 How to contribute

If you would like to work on any of the contributions mentioned above, follow the steps below.

Important

To run the code locally in development mode, you'll need to have installed on your machine.

0. Read the Open Source Guide 📑

This is an optional step, but a helpful one. If in doubt, follow the guidelines in the Open Source Guide.

1. Browse the open issues 🔎

Check if someone else is already working on a similar feature. If there is an open issue you want to work on, and it hasn't been claimed, tag me in a comment to let me know you want to claim it.

If there is not an open issue related to the feature you want to work on, open a new one. Leave a detailed description of what you want to implement, and tag me on it. Add descriptive labels if appropriate.

2. Fork the repo 🔱

Once the issue has been assigned to you, set up the repository on your local machine.

• Fork the repository into your GitHub account.

• Clone the repo in your local machine.

  git clone https://github.com/<your_github_username>/navbrix-api.git

• Clone the NavCraft API repo in the same directory, you'll need its database to run the code.

  git clone https://github.com/AndresPradGo/navcraft-api.git

• Start a feature branch.

  cd navbrix-api
  git switch -c <feature_or_bugfix>/<feature_name>

3. Run the Docker container

Once you've created a new feature branch, you can start working on the code. The repository has a Dockerfile.dev and docker-compose.dev.yml file to run in development mode:

• First, you can adjust the default environment variables of the project in the docker-compose.dev.yml file.

  ENV_VARIABLE	SERVICE	COMMENT
  MYSQL_ROOT_PASSWORD	database	Database password.
  MYSQL_DATABASE	database	Name of the database.
  NAVCRAFT_API_DB_PASSWORD	navcraft-api	Database password. Must equal MYSQL_ROOT_PASSWORD
  NAVCRAFT_API_DB_HOST	navcraft-api	IP or domain where the database is running.
  NAVCRAFT_API_DB_NAME	navcraft-api	Name of the database. Must equal MYSQL_DATABASE
  NAVCRAFT_API_MASTER_USER_NAME	navcraft-api	Name of the master user to migrate into the database.
  NAVCRAFT_API_MASTER_USER_EMAIL	navcraft-api	Email of the master user to migrate into the database.
  NAVCRAFT_API_MASTER_USER_WEIGHT	navcraft-api	Weight of the master user to migrate into the database.
  NAVCRAFT_API_MASTER_USER_PASSWORD	navcraft-api	Password of the master user to migrate into the database.
  NAVCRAFT_API_JWT_SECRET_KEY	navcraft-api	Secret key used to sign and verify JWTs.
  NAVCRAFT_API_JWT_ALGORITHM	navcraft-api	Algorithm used to sign and verify JWTs.
  NAVCRAFT_API_SENTRY_DSN	navcraft-api	DSN used to track the project's issues on Sentry.
  DATABASE_URL	navbrix-api	Use MYSQL_DATABASE and MYSQL_ROOT_PASSWORD
  NAVBRIX_API_NAVCRAFT_API_URL	navbrix-api	NavCraft API's URL, only used for the documentation.
  NAVBRIX_API_JWT_SECRET_KEY	navbrix-api	Must equal NAVCRAFT_API_JWT_SECRET_KEY
  NAVBRIX_API_JWT_ALGORITHM	navbrix-api	Must equal NAVCRAFT_API_JWT_ALGORITHM
  NAVBRIX_API_SENTRY_DSN	navbrix-api	DSN used to track the project's issues on Sentry.

• Next, build the docker images and run the docker container:

  docker-compose -f docker-compose.dev.yml build
  docker-compose -f docker-compose.dev.yml up -d

• Finally, troubleshoot. If the docker container doesn't run properly on the first try, it's most likely due to a docker network problem, or because any of the ports are occupied.

  • First, try restarting the navcraft-api container, this will solve the network problem:

    docker restart navbrix-api-navcraft-api-1

  • If the container keeps crashing because a port is occupied, open the docker-compose.dev.yml file and adjust the mapped ports. The default ports are:

    SERVICE	CONTAINER PORT	MAPPED TO
    database	3306	3307
    navcraft-api	8000	8000
    navbrix-api	3000	3000

• The three will run on the localhost 127.0.0.1 and their respective port. NavBrix API, for example, will run on:

  http://127.0.0.1:3000
  

Tip

The /src directory in the host, is being mapped to the /src directory in the container. Thus, any changes you save will be automatically shared to the container. However, the package.json and package-lock.json files are not being mapped. If you install a new library, you'll need to rebuild the image for it to show in the container.

4. Submit a pull request

After committing your code following commit best practices, you're ready to submit your changes.

• First, push the changes to your forked repo.

  git push origin <feature_or_bugfix>/<feature_name>

• Then, open a pull request to the main branch.