Federal Firearms License lookup and search service with RESTful API and web components
A high-performance HTTP server for Federal Firearms License (FFL) verification. Load FFL data from ATF.gov into memory and provide fast lookups, proximity search, and advanced filtering via REST API.
- 🔍 License Lookup - O(1) lookups by FFL number
- 📍 Proximity Search - Find FFLs near ZIP code or coordinates (requires
-geocode-fflsflag) - 🔎 Advanced Filtering - Search by name, city, state, license type
- 🌐 Geocoding - Embedded ZIP code database with 42K+ US ZIP codes
- 🧩 Web Components - Framework-agnostic UI components
- ⚡ Fast & Lightweight - In-memory storage, standard library HTTP
- 🔄 Auto Updates - Automatic data downloads from ATF.gov
- 💾 Geocache - Cache geocoded addresses for instant subsequent loads
- 🛠️ Operational Scripts - Automated geocoding and maintenance tools
# Clone repository (includes pre-geocoded data)
git clone https://github.com/wadearnold/ffl-verify.git
cd ffl-verify
# Build and run (includes proximity search and demo app)
make build
make runServer starts at http://localhost:8080 with:
- API endpoints at
/api/v1/* - Demo application at
/
Docker:
docker-compose up -dThe API provides RESTful endpoints for FFL lookup and search. Pre-geocoded data is included for instant proximity search.
# Health check
curl http://localhost:8080/api/v1/health
# Lookup by FFL number (supports multiple formats)
# Abbreviated format (with dashes)
curl http://localhost:8080/api/v1/ffl/1-66-00332
# Full format (with dashes)
curl http://localhost:8080/api/v1/ffl/1-66-003-01-6L-00332
# Full format (without dashes)
curl http://localhost:8080/api/v1/ffl/166003016L00332
# Search by name/state
curl "http://localhost:8080/api/v1/ffl/search?name=gun+shop&state=AZ"
# Proximity search by ZIP code (with license type filtering)
curl "http://localhost:8080/api/v1/ffl/search?zip=85001&radius=25&type=01"
# Proximity search by coordinates
curl "http://localhost:8080/api/v1/ffl/search?lat=33.4484&lon=-112.0740&radius=50"See API Reference for complete endpoint documentation.
The included demo application showcases all FFL Verify features in an interactive web interface:
- License Lookup - Search by FFL number with format help and validation
- Proximity Search - Find FFLs near a ZIP code or coordinates with distance sorting
- Advanced Filtering - Filter by license type, active status, and more
- Name/Location Search - Text-based search across business names, cities, and states
Visit http://localhost:8080 when running make run to explore the demo.
The demo uses the same web components that you can embed in your own applications.
This service provides framework-agnostic web components that can be embedded in any web application. Production applications should embed these components in their own frontend, not use the demo page.
Embedding in your application:
<!-- Copy web components from ./web/components/ to your project -->
<script src="/components/ffl-lookup.js"></script>
<ffl-lookup api-url="https://your-api-server.com"></ffl-lookup>Works with React, Vue, Angular, or vanilla JavaScript.
See Web Components Guide for complete integration instructions.
- API Reference - Complete endpoint documentation
- Web Components - UI component integration guide
- Deployment - Docker, configuration, monitoring
- Development - Contributing, testing, project structure
- Geocoding Guide - FFL address geocoding and maintenance
All configuration can be set via command-line flags or environment variables. The binary is located at ./bin/ffl-verify-server after running make build.
| Flag | Environment Variable | Default | Description |
|---|---|---|---|
-port |
PORT |
8080 |
HTTP server port |
-data-dir |
DATA_DIR |
./data |
FFL data directory |
-auto-download |
AUTO_DOWNLOAD |
true |
Auto-download from ATF.gov |
-download-interval |
DOWNLOAD_INTERVAL |
24h |
Update check interval |
-geocode-ffls |
GEOCODE_FFLS |
false |
Enable proximity search (instant with pre-geocoded data) |
-serve-demo |
SERVE_DEMO |
false |
Serve demo page (for testing only, not for production) |
Examples:
# Development (use make run for quick start with demo)
make run
# Production: API-only (no demo page)
./bin/ffl-verify-server
# Production with proximity search (recommended)
./bin/ffl-verify-server -geocode-ffls=true
# Using environment variables
PORT=3000 GEOCODE_FFLS=true ./bin/ffl-verify-server
# Custom data directory and port
./bin/ffl-verify-server -data-dir=/var/lib/ffl-data -port=9000 -geocode-ffls=true✅ Pre-geocoded data is included in this repository!
The repository includes a pre-geocoded master cache (data/ffl-geocache.json) with 99.8% success rate (77,470 out of 77,611 FFLs geocoded). You can enable proximity search immediately:
# Start server with proximity search enabled (instant startup!)
./bin/ffl-verify-server -geocode-ffls=trueWhat's included:
- Pre-geocoded master cache (37 MB, 99.8% success rate)
- September 2025 FFL data (77,611 records)
- ZIP code database (42,183 US ZIP codes)
Monthly ATF Updates:
When new FFL data is released (monthly), run incremental geocoding to update:
# Download and geocode new/changed FFLs (10-15 minutes)
./bin/ffl-verify-server -geocode-ffls=true -auto-download=trueThe incremental system:
- Reuses ~90% of cached geocodes (instant)
- Only geocodes new/changed FFLs (~5,000-10,000)
- Takes 10-15 minutes (not 2-4 hours!)
- Maintains master cache automatically
See Geocoding Guide for maintenance and troubleshooting.
Apache 2.0 - See LICENSE
- ATF.gov - FFL data source
- US Zip Codes JSON - ZIP code database
- geodist - Distance calculations