EMS Reach

EMS Reach is a Spring Boot web application that estimates ambulance access for a U.S. address.

Features

• Address lookup flow with Mapbox-powered address suggestions
• Nearest EMS station candidate selection via Haversine distance
• Drive-time ranking via Mapbox Matrix API
• Route geometry rendering via Mapbox Directions API
• Desert classification:
  • Covered: < 25 minutes
  • Ambulance Desert: 25-35 minutes
  • Severe Ambulance Desert: > 35 minutes

Tech Stack

• Java 21
• Spring Boot 3.x
• Maven
• Thymeleaf + Bootstrap 5
• Mapbox GL JS

Required Environment Variables

• MAPBOX_PUBLIC_TOKEN (browser-side map + address suggestions)
• MAPBOX_SECRET_TOKEN (server-side Matrix/Directions calls)
• APP_ENV (dev or prod, optional)
• APP_VERSION (optional)

Run Locally

mvn spring-boot:run

Open http://localhost:8080.

Test

mvn test

Refresh EMS Station Data

The production station dataset is generated from the live federal ArcGIS service used by HIFLD/USGS emergency response structures.

Run:

./scripts/refresh-ems-stations.sh

Script requirements:

• curl
• jq
• POSIX shell tools (awk, sort, wc)

This refreshes:

• Ambulance_Services (layer 1)
• Fire_Stations_EMS_Stations (layer 2)

Data scope note:

• Default (1 2) prioritizes broad emergency response coverage and avoids urban gaps.
• If you need strict ambulance-only facilities, run with EMS_SOURCE_LAYERS=1.

Output:

• src/main/resources/data/ems-stations.csv
• Header: station_id,station_name,latitude,longitude,address,city,state,zip

Current Dataset Snapshot

This section is the single source of truth for exact checked-in dataset snapshot details.

• File: src/main/resources/data/ems-stations.csv
• Scope: combined Ambulance_Services (1) + Fire_Stations_EMS_Stations (2)
• Row count: 59,096 data rows
• Snapshot file modified: March 05, 2026
• Refresh command: ./scripts/refresh-ems-stations.sh

The script enforces:

• pagination (1000 records/page)
• geometry conversion to WGS84 (outSR=4326)
• de-duplication by station id
• minimum row threshold (EMS_MIN_ROWS, default 10000)

Notes

• src/main/resources/data/ems-stations.csv is production data and should be refreshed periodically.
• The app is designed for planning awareness, not real-time EMS dispatch availability.