AirFlow

Passenger Flow Analytics for Dublin Airport

AirFlow is a Django web application that estimates and visualises passenger flow at Dublin Airport using commercially accessible flight schedule data. The system retrieves live flight data from the AviationStack API, applies a five-stage heuristic estimation algorithm to predict hourly passenger volumes, and renders the results as a gate-driven pathway heatmap on Google Maps.

Built as a Final Year Project for BSc Computer Science at Technological University Dublin.

Author: Alexander Mackey (C22739165)
Year: 2025/2026

---

Features

• Gate-driven pathway heatmap rendered on Google Maps, showing predicted passenger density at physically accurate terminal locations for both Terminal 1 and Terminal 2
• Time slider covering all 24 hours of the day with sub-second client-side updates via parallel pre-fetching
• Flight search returning terminal, gate, and a personalised arrival time recommendation
• Analytics page with a Chart.js hourly flow graph, summary statistics, and confidence badges
• Real flight data sourced from the AviationStack API with automatic endpoint selection based on date
• 53-test automated unit test suite covering the data layer, application layer, and all API endpoints

---

Tech Stack

Layer	Technology
Backend	Django 4.2.7, Python
Database	PostgreSQL + PostGIS
Mapping	Google Maps JavaScript API, HeatmapLayer
Charts	Chart.js
Flight Data	AviationStack API (Basic tier)
Styling	CSS3, Font Awesome

---

Project Structure

airflow_project/
├── core/
│   ├── services/
│   │   ├── estimation_service.py       # Five-stage passenger estimation algorithm
│   │   ├── gate_coordinates.py         # GPS coordinates for all T1 and T2 gates
│   │   └── pathway_interpolator.py     # Time-aware heatmap point generation
│   ├── management/commands/
│   │   └── scrape_flights.py           # AviationStack multi-endpoint scraper
│   ├── templates/core/
│   │   ├── map.html                    # Live View page
│   │   └── analytics.html             # Analytics page
│   ├── static/core/
│   │   ├── css/
│   │   │   ├── style.css              # Shared styles
│   │   │   ├── map.css                # Map page styles
│   │   │   └── analytics.css          # Analytics page styles
│   │   └── js/
│   │       ├── main.js                # Shared JavaScript
│   │       ├── map.js                 # Map page JavaScript
│   │       └── analytics.js           # Analytics page JavaScript
│   ├── models.py                       # Database models
│   ├── views.py                        # API endpoints and page views
│   ├── urls.py                         # URL routing
│   └── tests.py                        # 53-test automated test suite
├── airflow_project/
│   ├── settings.py
│   └── urls.py
├── manage.py
└── requirements.txt

---

Setup and Installation

Prerequisites

• Python 3.10+
• PostgreSQL with PostGIS extension
• A Google Maps JavaScript API key with Maps and Visualization libraries enabled
• An AviationStack API key (Basic tier or above)

1. Clone the repository

git clone <repository-url>
cd airflow_project

2. Create and activate a virtual environment

python -m venv airflow_env
airflow_env\Scripts\activate        # Windows
source airflow_env/bin/activate     # macOS/Linux

3. Install dependencies

pip install -r requirements.txt

4. Create a .env file in the project root

AVIATIONSTACK_API_KEY=your_aviationstack_key_here
GOOGLE_MAPS_API_KEY=your_google_maps_key_here
SECRET_KEY=your_django_secret_key_here
DEBUG=True
DATABASE_NAME=airflow_db
DATABASE_USER=your_db_user
DATABASE_PASSWORD=your_db_password
DATABASE_HOST=localhost
DATABASE_PORT=5432

5. Create the database

createdb airflow_db
psql airflow_db -c "CREATE EXTENSION postgis;"

6. Run migrations

python manage.py migrate

7. Load reference data

python manage.py load_reference_data

8. Scrape flight data

python manage.py scrape_flights --date 2026-04-22 --clear

9. Run the development server

python manage.py runserver

Navigate to http://127.0.0.1:8000/ to view the Live View, and http://127.0.0.1:8000/analytics/ for the Analytics page.

---

Running Tests

python manage.py test core --verbosity=2

All 53 tests should pass in approximately 2.7 seconds.

---

API Endpoints

Endpoint	Method	Description
/	GET	Live View map page
/analytics/	GET	Analytics page
/api/predictions/hourly/	GET	Hourly passenger predictions
/api/heatmap/dynamic/	GET	Gate-driven pathway heatmap points
/api/flights/search/	GET	Flight search and arrival recommendation
/api/debug/pathways/	GET	Terminal pathway debug endpoint

Query parameters: airport=DUB, date=YYYY-MM-DD, hour=0-23, flight_number=EI101

---

AviationStack Endpoint Strategy

The scraper automatically selects the correct AviationStack endpoint based on the target date:

Date range	Endpoint	Gate data
Today and historical	/v1/flights	Yes
1-6 days ahead	/v1/routes	No -- dead zone
7+ days ahead	/v1/flightsFuture	Yes

Dates in the 1-6 day range should not be re-scraped once gate data has been acquired, as the /v1/routes endpoint returns no gate information and will overwrite existing gate assignments with null values.

---

Known Limitations

• The AviationStack Basic tier returns null for aircraft type on /v1/flights responses. Airline-based heuristics are used as a fallback.
• Gate data is unavailable for dates 1-6 days ahead due to the AviationStack dead zone.
• Gate 13 and single-digit gate values are AviationStack placeholder identifiers for Ryanair operations, not physical gate positions. These are routed to Pier 1.
• The Google Maps HeatmapLayer was deprecated by Google in May 2025 with planned removal in May 2026. The system functions correctly within the April 2026 submission window.
• The system models departing passengers only. Arrival flow is not included.

---

License

This project was developed for academic purposes at Technological University Dublin and is not licensed for commercial use.