The nerdymark.com Public API - Now with Swagger Docs

5 min read

Over the years this site has quietly grown a bunch of JSON endpoints - some serious, some very much not. As of today they're all documented with Swagger at nerdymark.com/apidocs, powered by Flasgger. No API keys, no signup, no rate cards. Just be gentle: everything below runs on one small Elastic Beanstalk instance that also has to render Wordle solvers.

Here's the tour.

Public safety data

The workhorses. These aggregate official open-data feeds from Bay Area cities, cache them server-side, and refresh daily. They power the Caw safety map and the crime hotspots dashboard.

GET /api/public-safety-status - start here. It's the table of contents: every loaded city/service cache with incident counts and freshness timestamps. The cache_keys it returns (like san-jose_police) map directly onto the next endpoint.

GET /api/public-safety/{city}/{service} - the full incident feed for one source. Add ?days=3 to narrow the window.

curl "https://nerdymark.com/api/public-safety/san-jose/police?days=1"

GET /api/public-safety/nearby?lat=&lon= - my favorite of the bunch. Give it a coordinate and it figures out which regional feeds cover that point, then returns every cached incident within a mile. This is the closest thing to "is something happening near me?" as an API call.

curl "https://nerdymark.com/api/public-safety/nearby?lat=37.3382&lon=-121.8863"

GET /api/location-analytics - ranked hotspot addresses with incident counts, the same ranking that builds the hotspots dashboard and its sitemap.

GET /api/location/{address} - metadata and incident history for one specific address (percent-encoded).

GET /api/address/{address}/comments - community comments left on an address's incident page, auto-expiring after 30 days.

GET /api/geocoding-stats - cache statistics for the geocoder that turns all those addresses into map pins. Mostly here so I can check on it, but you're welcome to watch too.

Caw

Caw is this site's ephemeral, location-based social feed. Posts live for exactly one hour, which is either a design statement or a liability shield, depending on who's asking.

GET /api/caws - the live feed. Pass lat and lon and you only get caws within about a mile of that point, same as the map view.

GET /api/ice-sightings - active community-reported ICE sightings from the last 24 hours, with reverse-geocoded addresses.

POST /api/ice-sighting - the one true public write endpoint. Send JSON with latitude, longitude, timestamp, and an optional description (sanitized, capped at 500 characters). Reports expire after 24 hours and the endpoint is rate-limited.

curl -X POST https://nerdymark.com/api/ice-sighting \
  -H "Content-Type: application/json" \
  -d '{"latitude": 37.33, "longitude": -121.88,
       "timestamp": "2026-07-07T12:00:00Z",
       "description": "Two vehicles near the courthouse"}'

Honeypot

GET /api/wall-of-shame - the newest 50 bots and vulnerability scanners that requested one of this site's decoy paths (wp-login.php and several hundred juicier-looking friends). Sanitized IP, path, and user agent, newest first. They came looking for vulnerabilities and found a leaderboard.

Site odds and ends

GET /socials.json - where to find me, machine-readable.

GET /poachometer.json - a machine-readable contract describing exactly what it would take to poach me. Recruiters can now skip the "quick call" and just parse JSON. Serious inquiries only, unless very funny.

GET /python_version - which Python this site runs on. Useful to exactly one person, and that person is me after a platform upgrade.

GET /cutevid/status.json - the video currently featured on cutevid.com, for notification polling.

The details

Docs are generated with Flasgger, which turns YAML blocks in the Flask route docstrings into an OpenAPI spec (/apispec_1.json) and a Swagger UI. It's opt-in per route, so admin and internal endpoints never appear in the docs by accident. Every documented endpoint is unauthenticated and read-only except the ICE sighting report.

If you build something with any of this, tell me about it - especially if it's weird.

More in Technology

▲