Overview
All API endpoints are read-only and return JSON, except badge endpoints which return SVG. Public HaulMP data is cached server-side before being exposed here, so a visitor does not directly poll HaulMP.
DEVELOPER
API documentation
Read-only JSON endpoints backed by the dashboard cache and local history database.
Summary
GET/api/summary
Small one-request overview containing service state, player count, busiest city and active service incidents.
fetch("/api/summary").then(r => r.json()).then(console.log)Status
GET/api/status
Current state, latency and uptime for Website, Live Map, Companies, Accounts and Community.
GET/api/history?service=website&hours=24
service: website, map, vtc, accounts or forum. hours: 1–2160.
Network
GET/api/network
Current player count plus 24-hour average, peak and raw history.
GET/api/network-range?range=1m
Supported ranges: 24h, 7d, 1m, 6m, 1y. Long ranges are bucketed for graph performance.
Traffic
GET/api/traffic?limit=50
Latest detected city ranking. limit can be 1–200. Each row contains rank, country, players, trend and congestion level.
City detail
GET/api/city/calais?range=7d
Current, average, peak, current rank and historical traffic for one city. City slugs are case-insensitive URL-safe names.
Example
curl "/api/city/calais?range=24h"
Incidents
GET/api/incidents
Recorded service availability incidents.
GET/api/live-events
Latest cached public live-map events returned by HaulMP's frontend source.
Badges
GET/badge/status.svg
GET/badge/players.svg
GET/badge/uptime.svg
GET/badge/traffic.svg
Dynamic SVGs with a short public cache. Legacy /badge.svg still returns the status badge.
Player lookup
GET /api/player/:player
Looks up a player by live-map player name or ID. This endpoint only reports the current public live state and does not expose stored location history.
HaulMP profile widget
GET /api/profile/:handle
GET /widget/profile/:handle.svg
GET /badge/profile/:handle.svg
Loads a public HaulMP forum profile by stable account handle and renders a large embeddable SVG driver card with account status, company and public driving/community stats.
Profile badge customization
GET /widget/profile/:handle.svg
Optional query parameters: accent (6-digit hex), bg (cover, gradient, minimal), avatar, status, company, meta, stats_visible, and stats (four comma-separated values from distance, driving, deliveries, reputation, posts, threads).
Online players
GET /api/players
Returns all players currently visible on the public HaulMP live map, including parsed VTC tag, online activity (Driving, Safe Zone or Idling) and nearest known city.