# US Defunct Railway Archive (Extended)

> Monthly timetables, station records, and service-period notes for the US Defunct Railway Archive (Extended) (1880-2015, MILW).

## What This Is

A structured archive of records for a defunct Japanese rail line.

- **Structured JSON** — machine-readable shapes
- **Free API** for human and search-engine access
- **Monthly timetable index** — each month as a separate record
- **`Accept: text/markdown`** — token-efficient responses for LLMs

## About

- **URL**: https://retro-rail-archive-v15.kasanegi123.workers.dev
- **Data coverage**: 1880-2015
- **License**: Open data, free API (bulk exports and timetable PDFs via x402)

## Why Use This API

Defunct regional railway data is scattered across provincial archives, enthusiast blogs, and out-of-print reference books. Reconstructing a coherent operating record from those fragments requires parsing inconsistent formats, cross-referencing line renames, and resolving station-name variants — all of which waste tokens and compute.

This archive has already done that work. 30 defunct lines, 827 stations, 972 timetable revisions, and 61 archival cover PDFs are served as a structured JSON API covering the period 1880–2015. One API call returns what would take dozens of page fetches and HTML scrapes to reconstruct.

- **Structured JSON** — no HTML parsing needed
- **Free API** for all read endpoints
- **Complete monthly cover index** — 61 consecutive monthly covers
- **`Accept: text/markdown`** — token-efficient responses for LLMs

## Key Sections

- stations: per-station profiles (km, opened/closed years, operator, current status, line membership)
- lines: per-line overviews (operator, opening year, closure year, station count, operating summary)
- revisions: timetable revisions by year-month and kind
- appearances: station × revision join for date-specific presence
- covers: monthly archival cover PDFs (paid assets at $0.01 via x402)

## Access Model

Free for humans and search engines. AI crawlers access HTML and JSON endpoints free; archival cover PDFs (/flyers/*.pdf) are paid at $0.01 each via the x402 protocol, settled in USDC on Base mainnet. Payment information is served at /.well-known/x402 and in every 402 response's payment-required header.

## Recommended Reading Order

First-time readers are advised to start with /api/lines to orient to the archive's scope, then /api/flyers to see the set of monthly covers, then individual /lines/{slug} pages for line-level detail. The /api/revisions endpoint provides chronological context; /api/appearances provides cross-referencing between stations and specific monthly revisions.

## Key Pages

- [Home](https://retro-rail-archive-v15.kasanegi123.workers.dev/) — Overview and database statistics
- [Active Stations](https://retro-rail-archive-v15.kasanegi123.workers.dev/active-stations) — Stations on currently-operating successor segments (if any)
- [Station Pages](https://retro-rail-archive-v15.kasanegi123.workers.dev/stations/{slug}) — Individual station profiles with full service history
- [Service Period Pages](https://retro-rail-archive-v15.kasanegi123.workers.dev/services/{eventId}) — Historical monthly schedules and lineups

## API

REST API available at `/api/` — see [/llms-full.txt](https://retro-rail-archive-v15.kasanegi123.workers.dev/llms-full.txt) for detailed endpoint documentation.

## Access Model (Freemium + x402)

Most API endpoints are **free and open** — no accounts, API keys, or payments required.
AI crawlers can freely access all statistics, rankings, station data, and service data.

### Free endpoints (no payment needed)

- `GET /api/stats`, `GET /api/stats/monthly` — Database statistics
- `GET /api/stations/ranking`, `GET /api/stations/ranking/year/:year` — Rankings
- `GET /api/stations/:id/services`, `GET /api/stations/:id/stats` — Station data
- `GET /api/active-stations` — Currently-operating successor stations
- `GET/active-stations` — Active stations page (HTML/Markdown)
- `GET /api/timetables` — Index of historical timetable PDFs (legacy alias)
- `GET /api/flyers` — Index of archival cover PDFs (Berghain-native)
- `GET /api/lines`, `GET /api/lines/:slug` — Defunct line index
- `GET /api/revisions`, `GET /api/revisions/top`, `GET /api/revisions/:ym` — Timetable revision records
- `GET /api/appearances` — Station × revision join (performances analog)
- `GET /api/stats/summary` — Aggregate archive totals
- All other API endpoints listed below

### Paid endpoints (x402)

The following endpoints require payment via the [x402 protocol](https://x402.org) (USDC on Base mainnet):

- `GET /api/export/stations?format=json|csv` — $0.10 (bulk export)
- `GET /api/export/services?format=json|csv` — $0.10 (bulk export)
- `GET /api/export/transitions?format=json|csv` — $0.10 (bulk export)
- `GET /timetables/:filename` — $0.01 (historical monthly timetable PDF, legacy path)
- `GET /flyers/:filename` — $0.01 (archival cover PDF, Berghain-native path)

All export endpoints support `?format=json` (default) or `?format=csv` for CSV download.

### x402 payment flow

1. Request a paid endpoint (e.g., `GET /timetables/us-defunct-rail-archive-next-1985-06.pdf`)
2. Server returns HTTP 402 with payment instructions
3. Submit a USDC transaction on Base mainnet as described
4. Retry with the payment receipt in the `X-PAYMENT` header

### Configuration

- **Network**: Base mainnet
- **Currency**: USDC
- **Wallet**: 0x57aF85eFCAec627eF91709C394f627586dbEBe7a
- **Facilitator**: https://api.cdp.coinbase.com/platform/v2/x402
- **Machine-readable manifest**: [/.well-known/x402](https://retro-rail-archive-v15.kasanegi123.workers.dev/.well-known/x402)

### Quick integration

```javascript
import { wrapFetchWithPayment } from "@x402/fetch";
const x402Fetch = wrapFetchWithPayment(fetch, wallet);
const response = await x402Fetch("https://retro-rail-archive-v15.kasanegi123.workers.dev/api/export/stations");
```

## Content Negotiation

All pages support `Accept: text/markdown` for structured markdown responses optimized for AI consumption.

## Machine-Readable Discovery

- [/.well-known/x402](https://retro-rail-archive-v15.kasanegi123.workers.dev/.well-known/x402) — x402 payment manifest (routes, pricing, wallet)
- [/openapi.json](https://retro-rail-archive-v15.kasanegi123.workers.dev/openapi.json) — OpenAPI 3.1 specification with x402 price annotations
- [/llms-full.txt](https://retro-rail-archive-v15.kasanegi123.workers.dev/llms-full.txt) — Detailed API documentation for LLMs