Every offbeat roadside attraction on RoadsideAmerica.com — with a local SQLite cache, offline search, and superlative categories no other tool offers.
RoadsideAmerica.com is the web's best catalog of quirky US & Canada tourist attractions, but it has no API and a paywalled app. This CLI turns it into an agent-native, pipe-friendly tool: find what's near a place or coordinates, browse a whole state, pull the full writeup, and slice by superlative categories like biggest/smallest/tallest/weird-food. Everything is cached locally (fresh-on-read), every record links back to its source, and the scraper stays a polite, attributing, user-initiated citizen of the site.
Quick Start
# health + reachability check; no auth needed
roadside-america-pp-cli doctor
# quirky attractions near a city (geocoded), within 20 miles
roadside-america-pp-cli near "Austin, TX" --radius 20
# browse offbeat attractions in a state
roadside-america-pp-cli state TX --limit 10
# full writeup + location + source link for one attraction
roadside-america-pp-cli show 2055
Unique Features
These capabilities aren't available in any other tool for this API.
Local cache intelligence
-
category — Find the biggest, smallest, tallest, or weird-food attractions (and more) by classifying cached attractions locally.
Reach for this when the user wants superlatives or a themed slice (giants, muffler-men, weird-food) rather than a place- or state-scoped list.
roadside-america-pp-cli category biggest --json
-
stats — Summarize the local cache: counts by state and by category, plus totals.
Use to understand coverage of the local cache before planning, or to answer 'which state has the most offbeat stuff cached'.
roadside-america-pp-cli stats --agent
-
random — Pick a random offbeat attraction, optionally constrained by state or category.
Use for serendipity or road-trip inspiration when the user has no specific target.
roadside-america-pp-cli random --state TX
Route & comparison
-
trip — Collect quirky stops near a list of cities or coordinates in one call, deduped and labeled by stop.
Reach for this when planning a route and the user wants offbeat stops across several waypoints at once.
roadside-america-pp-cli trip "Austin, TX" "Waco, TX" --radius 15 --json
-
compare — Compare two states by offbeat-attraction count and surface a few top picks from each.
Use when the user is deciding between regions or wants a quick 'which state is weirder' answer.
roadside-america-pp-cli compare TX CA
Recipes
Quirky stops near coordinates, agent-friendly fields
roadside-america-pp-cli near 30.27,-97.74 --radius 25 --agent --select name,city,distance,source_url
Pass raw lat,lng to skip geocoding and select only the fields an agent needs.
Weird food across a cached state
roadside-america-pp-cli category weird-food --json
Classifies cached attractions by food keywords; populate the cache with state/near first.
Plan offbeat stops across a route
roadside-america-pp-cli trip "Austin, TX" "Waco, TX" "Dallas, TX" --radius 15 --json
Aggregates nearby attractions for each waypoint, deduped and labeled by stop.
Full writeup with source attribution
roadside-america-pp-cli show 2055 --json
Returns structured name/address/writeup plus the RoadsideAmerica.com source URL.
Usage
Run roadside-america-pp-cli --help for the full command reference and flag list.
Commands
raw
Raw RoadsideAmerica.com passthrough (HTML link/page extraction). Prefer the top-level near / state / show / category commands for structured output.
roadside-america-pp-cli raw by-state - Raw attraction links for a US/Canada state (HTML fragment).roadside-america-pp-cli raw detail - Raw attraction detail page (HTML).roadside-america-pp-cli raw nearby - Raw nearby attraction links for coordinates (HTML fragment).
Output Formats
# Human-readable table (default in terminal, JSON when piped)
roadside-america-pp-cli raw by-state --state example-value
# JSON for scripting and agents
roadside-america-pp-cli raw by-state --state example-value --json
# Filter to specific fields
roadside-america-pp-cli raw by-state --state example-value --json --select id,name,status
# Dry run — show the request without sending
roadside-america-pp-cli raw by-state --state example-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
roadside-america-pp-cli raw by-state --state example-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
roadside-america-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/roadside-america-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Slow responses or HTTP 429 — The CLI self-limits to ~1 request/3s and caches in SQLite; let it back off, or rely on cached data (results show fetched_at).
- near "" returns nothing — Widen --radius, or pass coordinates directly: near 30.27,-97.74 --radius 25.
- Geocoding a place name fails — Pass latitude,longitude directly to near/trip; geocoding uses keyless OSM Nominatim which may rate-limit.
- category returns few results — Categories classify the LOCAL cache; run state/sync/near first to populate, then re-run category.