FCC Tool

A comprehensive utility for managing and querying FCC amateur radio license database files, creating a local SQLite copy of the entire FCC ULS database for offline use. Includes both a command-line interface and a modern web interface.

Table of Contents 📑

• Overview
• Author and License
• Features
  • Web Interface
  • Database Management
  • Query Capabilities
• Installation
• Usage
  • Web Interface
  • Command Line Options
  • Examples
• Project Structure
• Configuration
• Database Documentation
• Troubleshooting
• Contributing
• Changelog

Overview

FCC Tool is a command-line and web application that creates and maintains a complete local SQLite copy of the FCC Amateur Radio License database. This allows you to develop applications that can look up any callsign, entity, or license name without requiring internet connectivity. The tool provides functionality to download and update the database from the FCC's Universal Licensing System (ULS), look up amateur radio call signs, search for licensees by name or state, and maintain the database for optimal performance.

The offline nature of this tool makes it particularly valuable for amateur radio operators in the field, emergency communications scenarios, or any situation where internet access may be limited or unavailable.

↑ Back to Table of Contents

Author and License

Author: Tiran Dagan (Backstop Radio)
Contact: tiran@tirandagan.com
License: MIT License

Copyright (c) 2025 Tiran Dagan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

↑ Back to Table of Contents

Features

Web Interface

[Features > Web Interface]

FCC Tool includes a modern, responsive web interface (fcc_tool_web.py) that provides an elegant way to search and view FCC amateur radio license data:

Search Interface

• Clean, Modern Design: A beautiful, intuitive search interface
• Multiple Search Options:
  • Callsign lookup (e.g., W1AW)
  • Name search (partial or full)
  • State filtering with searchable dropdown
• Keyboard Shortcuts: Quick navigation using Alt + C/N/S
• Search Tips: Built-in help and search suggestions
• Recent Searches: Track and quickly access your recent searches

Clean, modern search interface with keyboard shortcuts and search tips

Search Results

• Flexible Views:
  • Table view for compact listing
  • Card view for detailed information
• Advanced Filtering:
  • License status (Active/Inactive)
  • License class (Extra, General, Technician)
  • Sort by various fields
• Pagination: Browse through large result sets
• Quick Actions: Direct access to detailed profiles

Search results with advanced filtering and sorting options

Profile View

• Detailed Information: Comprehensive license details
• Interactive Map: View licensee location
• Personal Information: Entity details and contact info
• License Details: Status, class, dates, and more
• Dark Mode: Toggle between light and dark themes
• Responsive Design: Works on desktop and mobile

Detailed profile view with interactive map and comprehensive license information

The web interface is built with:

• Flask for the backend
• Bootstrap 5 for responsive design
• Leaflet.js for interactive maps
• Modern CSS with animations and transitions
• Session management for recent searches
• Real-time search filtering

↑ Back to Table of Contents

Database Management

[Features > Database Management]

FCC Tool can automatically download and update the FCC amateur radio license database from the FCC's ULS database downloads page. The tool checks for updates by comparing the last modified date of the remote file with your local copy, ensuring you only download new data when it's available.

Key features:

• Automatic update detection: Checks if a new version is available before downloading
• Efficient data processing: Downloads, extracts, and loads data into an SQLite database
• Optimized data loading: Uses temporary tables and bulk operations for fast data loading
• Index creation: Automatically creates optimized indexes for fast searching
• Cleanup: Removes temporary files after processing to save disk space

The tool also provides several options for maintaining and optimizing the database:

• Compaction: Reclaims unused space in the database file
• Optimization: Removes unused tables and columns to reduce database size
• Index rebuilding: Rebuilds database indexes to improve search performance

↑ Back to Table of Contents

Query Capabilities

[Features > Query Capabilities]

Call Sign Lookup

The primary function of FCC Tool is to look up FCC license information by call sign. This retrieves all available information for a specific amateur radio call sign from the database.

Name Search

You can search for FCC license records by name using a case-insensitive wildcard search that matches names in any position. This is useful for finding all licenses associated with a particular person or organization.

State Filtering

The tool allows you to search for records by state using the two-letter state code. This is helpful for finding all licensees in a specific geographic area.

Combined Searches

You can combine name and state filters to perform more targeted searches, such as finding all licensees with a specific name in a particular state.

↑ Back to Table of Contents

Installation

FCC Tool can be run directly from Python source or as a standalone executable. For detailed instructions on building and running the application, see the Build Documentation.

Quick Start

Running from Python Source

# Install dependencies
pip install -r requirements.txt

# Run the CLI application
python fcc_tool.py --help

# Run the web interface
python fcc_tool_web.py

The web interface requires additional Python packages:

• Flask
• Flask-Session
• Leaflet.js (included via CDN)

These are all included in requirements.txt.

Using Pre-built Executables

Download the latest release from the Releases page for your platform (Windows, Linux, or macOS).

↑ Back to Table of Contents

Usage

Using the Web Interface

[Usage > Web Interface]

To start the web interface:

python src/fcc_tool_web.py

This will start a Flask web server on port 5000. You can then access the web interface by opening a web browser and navigating to:

http://localhost:5000

The web interface provides:

1. Search Options:

   • Search by callsign (e.g., W1AW)
   • Search by name (partial or full)
   • Filter by state

2. Advanced Filtering:

   • License status (Active/Inactive)
   • License class (Extra, General, Technician)
   • Sort results by various fields

3. Keyboard Shortcuts:

   • Alt + C: Focus callsign field
   • Alt + N: Focus name field
   • Alt + S: Focus state field
   • Ctrl + T: Toggle dark/light theme

4. View Options:

   • Table view for compact listing
   • Card view for detailed information
   • Interactive map view for location data

Command Line Options

[Usage > Command Line Options]

FCC Tool provides a comprehensive set of command-line options for database management and querying:

Database Management Options

| Option | Description | |--------|-------------| | --update | Check for and download updates to the FCC database | | --force-download | Force download even if data is up to date | | --skip-download | Skip download and use existing data files | | --check-update | Check if an update is available without downloading | | --keep-files | Keep downloaded and extracted files after processing | | --quiet | Suppress INFO log messages (only show WARNING and above) | | --compact | Compact the database to reduce file size | | --optimize | Remove unused tables and compact the database | | --rebuild-indexes | Rebuild database indexes to improve search performance | | --active-only | Only keep active license records (license_status="A") in the database. Requires confirmation before deleting records |

Query Options

| Option | Description |