# EVE Emptiness — Public API for agents

> EVE Emptiness tracks activity across EVE Online's ~4,900 accessible k-space
> systems (jumps, PvP/NPC kills, sovereignty, incursions, faction warfare,
> industry indices) on an hourly cadence, and derives quietness, danger, trend,
> chokepoint, and jump-range intelligence. This file tells an autonomous agent
> how to consume it.

Base URL: https://jumps.tovdc.com/api/v1
Auth: none (read-only). Please send a descriptive `User-Agent`.
Discovery (machine-readable catalog): https://jumps.tovdc.com/api/v1
OpenAPI 3.1 spec: https://jumps.tovdc.com/api/v1/openapi.json
Human docs: https://jumps.tovdc.com/api.html

## Conventions
- Every success response is an envelope: `{ "data": ..., "meta": {...}, "links"?: {...} }`.
- Errors: `{ "error": { "status", "code", "title", "detail" }, "meta": {...} }` with the matching HTTP status.
- Pagination: `page` (1-based) + `page_size` (default 50, max 500). See `meta.pagination` and `links.next` / `links.prev`.
- Sparse fieldsets: `fields=name,region,activity_score` trims each item (`system_id` always kept).
- Caching: responses set `Cache-Control` and a weak `ETag`; success bodies are deterministic within their cache window, so `If-None-Match` yields real `304`s. `meta.cache.ttl_seconds` states the window.
- Rate limit: 240 requests / minute / IP. Watch `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`; back off on `429`.
- Freshness: activity data refreshes ~hourly from CCP's ESI. Coordinates/topology are stable.

## Endpoints
- `GET /systems` — list/filter/sort every system. Filters: `region`, `constellation`, `security=high|low|null`, `security_min/max`, `activity_min/max`, `jumps_min/max`, `kills_min/max`, `min_consistency`, `max_hub_distance`, `activity_type=pve|pvp|mixed|dead`, `trend=increasing|decreasing|stable`, and booleans `has_npc_station`, `quiet_now`, `incursion`, `sov_campaign`, `fw_contested`, `wormhole_access`. Sort: `sort=activity|weighted|jumps|kills|jumps_24h|kills_24h|npc_kills|consistency|hub|security|danger|neighbor|name` + `order=asc|desc`. Default: `activity` ascending (quietest first).
- `GET /systems/{id}` — one system, full live payload (activity, 24h totals, 30d trends, danger density, sov ADM, topology, hub distance).
- `GET /systems/{id}/history?days=90` — daily activity totals (1–365 days; older days from the permanent archive).
- `GET /systems/{id}/circadian` — 24-hour activity distribution.
- `GET /systems/{id}/sovereignty?days=30` — null-sec ADM change events.
- `GET /search?q=jita` — system-name autocomplete (min 2 chars).
- `GET /regions` — all regions with system counts.
- `GET /gate-camps` — chokepoints ranked by betweenness centrality (`sort=bottleneck|jumps|ship_kills|gate_count|security|activity`, filters `min_bottleneck`, `topology_type`, `region`, `min_jumps`). Paginated.
- `GET /forecast-inputs` — bulk forecaster feed: per system, up to 35 days of `[date, jumps, pvp_kills, npc_kills]` daily totals + `hour_distribution`, trend/consistency, topology context. Build your own model on it (the last daily entry is the partial in-progress day — exclude it).
- `GET /forecast/systems` — tomorrow's per-system forecast (nightly statistical model): `predicted_jumps`, `predicted_pvp_kills`, `hotspot_prob` (P of ≥15 PvP kills), `surprise_index` (Poisson z-score of predicted kills vs the system's own 7-day baseline — high = quiet system about to spike), `drivers` (timer/fw/momentum), `quiet_window` + `quiet_confidence`. `meta.target_day` names the day. Paginated; `sort=prob` (default) or `sort=surprise`.
- `GET /forecast/hotspots?limit=50&sort=prob|surprise` — just the ranked predicted-fight list. `sort=surprise` surfaces unusual upcoming fights instead of perennially busy systems (Jita is always p≈1; a 2-kills/day system with a sov timer is the interesting one).
- `GET /forecast/briefs` — daily LLM-written intel briefs (galaxy + per-region); `status: "fallback"` marks the deterministic statistical summary used when the LLM is offline.
- `GET /forecast/accuracy?days=30` — daily accuracy per model INCLUDING naive baselines (`naive-1d`, `ma7`) scored on identical windows: MAE/RMSE/MAPE, directional accuracy, hotspot Brier, quiet precision/recall. Check `blend-v1` beats `naive-1d` before trusting forecasts.
- `GET /fights/hotspots` — live PvP hotspots (`data.hotspots` + `data.summary`) with fight score, classification, and prime hour.
- `GET /fights/timers` — upcoming sovereignty campaign timers (scheduled fights) with defender names.
- `GET /map` — all systems with 3D coordinates (`pos_x/pos_y/pos_z`, meters) and overlay flags. One big spatial payload.
- `GET /jump-range?staging=Jita&mode=fastest` — gate-jump distance from a staging system to every system (`data.jumps` is `{ system_id: jumps }`). `mode=fastest|safest`. Light-year distance is computable client-side from `/map` coords (1 ly = 9.4607304725808e15 m).
- `GET /wormholes` — live Thera/Turnur wormhole connections (Eve Scout), each fused with our activity data (k-space destinations: `activity_score`, `currently_quiet`, `hub_distance`) or static class/effect (J-space). Per connection: `hub`, `system_name`, `wormhole_type`, `max_ship_size`, `expires_at`, `eol` (within ~4h of collapse), `security_status`. `meta.summary` has counts by hub/security/ship-size + EOL. ESI has no wormhole stats, so this + zKill are the only J-space sources.
- `GET /stats` — dataset coverage + collection health.
- `GET /health` — liveness + last-collection timestamp.

## Recipes
Quietest low-sec systems near a trade hub (good ratting/exploration targets):
  curl -s 'https://jumps.tovdc.com/api/v1/systems?security=low&sort=activity&order=asc&max_hub_distance=10&page_size=20&fields=name,region,activity_score,consistency_score,hub_distance'

Where are people dying right now (busiest PvP):
  curl -s 'https://jumps.tovdc.com/api/v1/fights/hotspots'

Is a target system within a defender's capital umbrella and how far by gate:
  curl -s 'https://jumps.tovdc.com/api/v1/jump-range?staging=1DQ1-A&mode=fastest'
  # combine with /map coordinates for light-year distance.

Full 90-day history for a system:
  curl -s 'https://jumps.tovdc.com/api/v1/systems/30000142/history?days=90'

Where will the fights be tomorrow (and can I trust that):
  curl -s 'https://jumps.tovdc.com/api/v1/forecast/hotspots?limit=20'
  curl -s 'https://jumps.tovdc.com/api/v1/forecast/accuracy?days=14'

Data © CCP Games via ESI. Derived metrics are free to use. Be a good citizen: cache, send a User-Agent, respect the rate limit.