NBPD UAS Pre-Flight

A static, read-only pre-flight page for New Brunswick (NJ) Police Department drone pilots. It's built for phones, needs no login, and is hosted on GitHub Pages.

A scheduled GitHub Action fetches TFRs, METAR/TAF, the NWS forecast and alerts, and the planetary Kp index every 10 minutes. It applies the thresholds in config.json and deploys data.json together with the page. The page re-polls data.json every 5 minutes. It computes sunrise, sunset and civil twilight in the browser.

Situational awareness aid only. The remote pilot in command remains responsible for the preflight assessment under 14 CFR 107.49 and for checking official FAA sources.

Setup

1. Enable Pages with GitHub Actions as the source. Go to Settings → Pages → Build and deployment → Source and choose GitHub Actions.
2. Set the NWS contact variable. Go to Settings → Secrets and variables → Actions → Variables → New repository variable and add NWS_CONTACT. Set it to an email address or URL where NWS can reach the page's maintainer, for example [email protected]. The NWS API requires an identifying User-Agent, which is sent as (nbpd-uas-preflight, <NWS_CONTACT>).
3. Run the workflow once. Go to Actions → Refresh pre-flight data → Run workflow. After that it runs every 10 minutes and on every push to main. The page URL appears on the run summary.
4. Check the deployment. Open the page, expand Data source status at the bottom, and confirm that every source shows ✅.

The workflow never commits to the repository. Each run builds a new Pages deployment with a fresh data.json.

Note: GitHub sometimes delays scheduled workflows by several minutes or more when it is under load. When that happens, the page shows DATA STALE once data.json is more than 30 minutes old.

Vercel deployment: any US ZIP code

main runs on Vercel (dfrpreflight.com), side by side with the GitHub Pages site.

• / shows a ZIP form. /08901 shows the pre-flight page for that ZIP; /08901/ redirects there.
• Use my location (on the form and on every location page) asks the browser for the device's position and opens /?lat=40.512&lon=-74.406 (3 decimals, about 100 m). Distances are then measured from that point, not a ZIP centre. The nearest ZIP supplies the state for the TFR filter and the "Near Edison, NJ" label; a point more than 50 NM from every US ZIP centre is refused as outside coverage.
• The page loads /api/data?zip=08901 (or /api/data?lat=…&lon=…). The function api/data.mjs looks the ZIP up in data/zips.json, builds that location's config (scripts/location.mjs) and runs scripts/fetch.mjs on demand. An unknown ZIP returns 404 and the page shows the form again.
• Vercel's CDN caches each ZIP's result for 5 minutes and serves a stale copy for up to 10 more while it refreshes, so data is at most about 15 minutes old, under the 30-minute DATA STALE limit. The TFR list, TFR details and Kp are the same for every ZIP, so a warm function instance shares them across ZIPs for 5 minutes.
• ?data=samples/… still previews the sample files, and /data.json still serves the fixed config.json location.

What changes per ZIP:

	Fixed config (config.json)	ZIP page
Centre	center	ZIP centre point from GeoNames (not the flight location; large rural ZIPs can be several NM across), or the device location
TFR states	tfrStates	the (nearest) ZIP's state plus bordering states
METAR / TAF	stations, tafStations	nearest stationCount (3) METAR and tafCount (2) TAF stations within stationSearchNm (60 NM), from an aviationweather.gov bounding-box query; no station in range is a CAUTION
Time zone	timeZone	from the NWS point lookup, else the device's zone

Thresholds, TFR radius and everything else come from config.json for every ZIP.

data/zips.json (about 41,000 ZIPs; territories and military APO/FPO codes are not included) is built from the GeoNames US postal-code file (CC BY 4.0; credited in the page footer). To refresh it:

curl -O https://download.geonames.org/export/zip/US.zip && unzip US.zip US.txt
node scripts/build-zips.mjs US.txt

Setup: import the repository in Vercel (framework preset Other, no build command), add the NWS_CONTACT environment variable, and set the production branch to main.

Editing config.json

Key	Meaning
center.lat, center.lon	Reference point for TFR distances, NWS forecast/alerts and sun times. Default: 40.4862, -74.4518.
tfrRadiusNm	Local TFRs farther than this are dropped. Default: 30.
tfrStates	FAA list state values checked for local TFRs.
stations	METAR stations, listed in display order.
tafStations	Stations to request TAFs for (only airports that issue one; KSMQ does not). Defaults to stations.
forecastHours	Number of hourly forecast rows shown.
staleMinutes	Age after which the page shows DATA STALE.
thresholds	Caution and no-go-review limits (see below).
airspaceRadiusNm	Radius for the airspace card and map (restricted areas, nearest controlled airspace). Default: 3.
thresholds.airspace	controlledLevel (1 = CAUTION) inside controlled airspace; zeroCeilingLevel (2 = NO-GO REVIEW) on a 0 ft facility map ceiling; nearNm (0.5) for "near a restricted area"; stadiumLevel (0 = information only). Agencies flying under a COA can lower these.
tfrDetailXmlUrls	Per-TFR XML URL patterns, tried in order. {id} becomes 6_1234 for NOTAM 6/1234. Edit these if the FAA moves the files.

Commit a change to config.json on main and the workflow redeploys automatically.

This is the beginning of the README. Read the rest at the original. Read the full README ↗