API Documentation

🚀 Getting Started

The NodelistDB API provides RESTful access to FidoNet node data with JSON responses. All endpoints support standard HTTP methods and return consistent JSON structures.

Base URL: https://nodelist.fidonet.cc/api/

🔍 Search Endpoints

Search Nodes

GET /api/nodes

Search for nodes using various criteria. All parameters are optional.

Query Parameters:
zone - Zone number (e.g., 1, 2, 3)
net - Net number
node - Node number
system_name - System name (partial match)
location - Location (partial match)
node_type - Node type (Hub, Host, Zone, etc.)
is_active - true/false for active nodes
is_cm - true/false for CM nodes
date_from - Start date (YYYY-MM-DD)
date_to - End date (YYYY-MM-DD)
latest_only - true/false, restrict to most recent nodelist only (default: false, includes all historical data)
limit - Results limit (default: 100, max: 200)
offset - Results offset for pagination

Examples:
GET /api/nodes?zone=2&limit=10&is_cm=true
GET /api/nodes?location=Berlin&latest_only=true
GET /api/nodes?system_name=BBS&date_from=2020-01-01

🎯 Node Specific Endpoints

Get Node Information

GET /api/nodes/{zone}/{net}/{node}

Retrieve information for a specific node, including current and historical versions.

Example:
GET /api/nodes/2/5001/100

Get Node History

GET /api/nodes/{zone}/{net}/{node}/history

Get complete historical records for a specific node.

Example:
GET /api/nodes/2/5001/100/history

Get Node Changes

GET /api/nodes/{zone}/{net}/{node}/changes

Get all detected changes and timeline events for a node.

Example:
GET /api/nodes/2/5001/100/changes

Get Node Timeline

GET /api/nodes/{zone}/{net}/{node}/timeline

Get timeline data optimized for visualization, including activity periods and gaps.

Example:
GET /api/nodes/2/5001/100/timeline

📊 Statistics Endpoints

Network Statistics

GET /api/stats

Get comprehensive network statistics including node counts, zone distribution, and capabilities.

Query Parameters:
date - Specific date for statistics (YYYY-MM-DD, defaults to today)

Example:
GET /api/stats?date=2023-12-01

Available Dates

GET /api/stats/dates

Get a list of all available dates for which statistics data exists in the database.

Example:
GET /api/stats/dates

Response:
{"dates": ["2023-01-07", "2023-01-14", "..."], "count": 52}

🛠️ System Endpoints

Health Check

GET /api/health

Check API service status and uptime.

Example Response:
{"status": "ok", "time": "2023-12-01T12:00:00Z"}

🗄️ Database Structure

Main Table: nodes

The database stores FidoNet nodelist data in ClickHouse with the following schema:

Core Identity Fields:
zone - Zone number (INTEGER)
net - Net number (INTEGER)
node - Node number (INTEGER)
nodelist_date - Date from nodelist (DATE)
day_number - Day of year (INTEGER)

Node Information:
system_name - BBS system name (TEXT)
location - Geographic location (TEXT)
sysop_name - System operator name (TEXT)
phone - Phone number (TEXT)
node_type - Zone/Region/Host/Hub/Pvt/Down/Hold (TEXT)
region - Region number if applicable (INTEGER)
max_speed - Maximum connection speed (TEXT)

Boolean Flags (computed):
is_cm - Continuous Mail (BOOLEAN)
is_mo - Mail Only (BOOLEAN)
has_binkp - Supports Binkp protocol (BOOLEAN)
has_inet - Has internet connectivity (BOOLEAN)
has_telnet - Supports Telnet (BOOLEAN)
is_down - Node is down (BOOLEAN)
is_hold - Node is on hold (BOOLEAN)
is_pvt - Private node (BOOLEAN)
is_active - Node is active (BOOLEAN)

Array Fields:
flags - All flags (TEXT[])
modem_flags - Modem-specific flags (TEXT[])
internet_protocols - Supported protocols (TEXT[])
internet_hostnames - Internet hostnames (TEXT[])
internet_ports - Internet ports (INTEGER[])
internet_emails - Email addresses (TEXT[])

Internet Configuration:
internet_config - Structured JSON configuration (JSON)

Conflict Tracking:
conflict_sequence - Sequence for duplicate nodes (INTEGER)
has_conflict - Indicates duplicate entries (BOOLEAN)

Primary Key:
(zone, net, node, nodelist_date, conflict_sequence)

Note: The database preserves duplicate node entries that exist in original FidoNet nodelists due to human error. Duplicates are tracked with conflict_sequence (0 for first occurrence, 1+ for duplicates) and marked with has_conflict = true.

📥 Nodelist File Downloads

Download Individual Nodelists

Download individual nodelist files directly. Files are automatically decompressed if stored as .gz:

Endpoint: GET /download/nodelist/{year}/{filename}

Example:
GET /download/nodelist/2024/nodelist.365
GET /download/latest (redirects to most recent nodelist)

Bulk Download Options

Year Archives

Endpoint: GET /download/year/{year}.tar.gz

Description: Download all nodelists from a specific year as a tar.gz archive

Example:
wget https://nodelist.fidonet.cc/download/year/2024.tar.gz

URL List for Mirroring

Endpoint: GET /download/urls.txt

Description: Text file containing all nodelist download URLs

Usage:

# Download all nodelists

                    wget -i https://nodelist.fidonet.cc/download/urls.txt


                    # Skip existing files (incremental sync)

                    wget -nc -i https://nodelist.fidonet.cc/download/urls.txt

Note: All download endpoints support HTTP range requests for resumable downloads. The server automatically handles .gz decompression transparently.

💾 Database Access

Query via API

Access the ClickHouse-backed database through the REST API endpoints documented above. The API provides efficient access to all nodelist data with filtering, pagination, and search capabilities.

Example API queries:

# Get all nodes in Zone 2

                    curl "https://nodelist.fidonet.cc/api/api/nodes?zone=2&limit=100"



                    # Search for nodes with Binkp support

                    curl "https://nodelist.fidonet.cc/api/api/nodes?has_binkp=true&limit=50"



                    # Get network statistics

                    curl "https://nodelist.fidonet.cc/api/api/stats"

Database Info: The ClickHouse database is updated weekly with the latest FidoNet nodelist data, providing high-performance analytics and time-series capabilities.

💡 Usage Examples

Using curl

# Search for nodes in Zone 2

curl "https://nodelist.fidonet.cc/api/api/nodes?zone=2&limit=5"

# Get specific node information

curl "https://nodelist.fidonet.cc/api/api/nodes/2/5001/100"

# Search by sysop name

curl "https://nodelist.fidonet.cc/api/api/nodes?sysop_name=John_Doe"

# Get network statistics

curl "https://nodelist.fidonet.cc/api/api/stats"

# Get available dates for statistics

curl "https://nodelist.fidonet.cc/api/api/stats/dates"

Response Format

All API responses use JSON format with consistent structure:

{

  "nodes": [...],

  "count": 42,

  "filter": {...}

}