Companion reference

GT-GridStats (“GTStats”)

Unofficial third-party site: gt-gridstats.com. API docs: /api-docs. About: /about. In chat we say “GTStats”; in code it’s GridStats / GRIDSTATS_*.

Welch Race Companion is not affiliated with GridStats, Polyphony Digital, or Sony. Companion profile / Sport / assets use their JSON API (Bearer on our Worker) and hosted CDN images only — plus catalogs bundled in the app. Player pages are outbound links. Repo markdown: docs/GRIDSTATS.md.

What GridStats offers

Indexes and preserves GT7 Sport Mode–adjacent history (championships, events, dailies, driver profiles). Built by GT-Skino; ecosystem includes gtgarage.racing and gtstreamers.com.

Public website (no API token)

Area	What it does
Home / PSN search	Public Online ID lookup + Daily Race A/B/C cards
Drivers	Browse indexed driver profiles
Dailies	Daily Race–focused views
Events	Championship / event browsing
API Documentation	Bearer auth + endpoint reference
GSTA Download	Windows OBS overlay (~109 MB) — not an image pack
System Status	Ops / availability
Discord (+ bot)	Community; bot for instant driver lookups (leagues)
Support / Contact	Funding + `gtgridstats@gmail.com`

Public CDN (no token)

Asset	Pattern	Our use
Car thumbnails	`/storage/car_thumbnails/car{code}.png`	Garage CDN thumbs + Coil 128 MB disk cache (~19 MB if all cached)
Maker logos (light)	`/storage/tuner_logos/light/tnr{id}.png`	Vendored in the app (~0.2 MB, 77 makers)
Maker logos (API slug)	`/storage/logos/{slug}.png`	Documented by their API samples
Track photos	TrackPhotos CDN	Android Coil venue stills
Player / home pages	`/player/{psn}`, `/`	Outbound links to their website

Metered JSON API (Bearer)

Authorization: Bearer YOUR_TOKEN_SECRET
Accept: application/json

Quota headers: X-Quota-Limit / X-Quota-Remaining · HTTP 429 when exhausted. Typical rate 10 req/min; regions is quota-free with a 30/min ceiling.

Game asset inventories

Method	Path	Notes
GET	`/api/assets/manufacturers`	Full maker index
GET	`/api/assets/manufacturers/{locale}`	Localized names
GET	`/api/assets/cars?page=`	Paginated catalog
GET	`/api/assets/cars/{id}/{locale?}`	By id / car_code / gt7_code
GET	`/api/assets/manufacturer/{id}/cars/{locale?}`	Maker fleet
GET	`/api/assets/manufacturer/{id}/{class}/{locale?}`	Fleet by class
GET	`/api/assets/regions`	Quota-free region registry

Racer snapshots

Method	Path	Notes
POST	`/api/racers`	Batch sync; max 16 IDs; new drivers staggered (~48s worst case)
GET	`/api/racers/{identifiers}`	Up to 16 PSNs; missing → `not_found`

Stats include DR/SR, points, races, wins, poles, clean races, license, garage, credits, play time, distance, and more.

Championship analytics

Method	Path	Notes
GET	`/api/series-{series}/drivers/{psn_list}`	Season/round tracker (e.g. Nations Cup rank + points)

Their docs UI lists Championship Analytics as three surfaces; the path above is the one documented in /api-docs. Prefer that page if they add more.

Big picture (Companion)

Two separate paths — the race HUD never talks to GridStats.

Path	What	GridStats?
Race HUD / voice / setups	PS5 LAN UDP (33739 / 33740) or Sim	Never
Companion screens	Profile, Sport Mode, Garage thumbs, optional assets	Yes (via Worker)

App / web companion
        │ HTTPS (no API key in the app)
        ▼
Welch Worker  https://gtdash.welchsoftware.net
        │ Authorization: Bearer <GRIDSTATS_API_TOKEN>
        ▼
GT-GridStats  https://gt-gridstats.com
  • JSON API     → Bearer token (metered)
  • Public CDN   → car thumbs / track photos

Worker proxy map

Our route	Upstream	Auth
`/api/racer/:psn`	`/api/racers/{psn}` only	Bearer required
`/api/sport/week`	Bearer `/api/dailies/this-week`	Bearer
`/api/assets/*`	Matching asset paths	Bearer
`/api/series/:series/drivers/:psnList`	`/api/series-{series}/drivers/…`	Bearer
`/api/health`	Local boolean only	—

Features we use today

Feature	Screen	How
DR / SR, points + band gauge to next letter, garage, wins, credits, license, collector, clean races	Profile (app + web)	Worker JSON API (`dr_points`); app maps community Sport Mode thresholds for “pts to next”
Daily Races A / B / C	Sport Mode	Bearer `/api/dailies/this-week` → `/api/sport/week`
Car class on detail	Garage	Worker `/api/assets/cars/{code}` when a row is opened
Car thumbnails	Garage	Public CDN `/storage/car_thumbnails/car{code}.png`
Track photo fallback	Tracks / Sport	Public TrackPhotos CDN when bundled art missing

Still stub

Championship series is proxied but has no UI. Full live car catalog / manufacturer / region inventories are available via Worker but unused in search UI (metered). Discord bot, Events, and GSTA stay on the GridStats site only.

Not from GridStats

Live telemetry / voice / setups → PS5 UDP / Sim
Searchable car / track / maker catalogs → bundled gt7info
Primary track art → vendored drawables
Weekly challenge copy → live feed only (no editorial placeholders)
Official leaderboards → gran-turismo.com deep links only

The 8 keys

They are candidate Bearer API tokens from the GridStats owner for their metered JSON API. You store one working token as the Worker secret GRIDSTATS_API_TOKEN. The mobile app never holds or shows them.

For: stable JSON profiles, live asset APIs, championship analytics.

Not: app keys, per-user logins, PSN passwords, Salsa20 telemetry keys, or the eight local preference keys on the device.

Status: Bearer on the Worker drives Profile JSON, assets, and Sport Mode Daily A/B/C via /api/dailies/this-week. Sport Mode falls back to bundled sport-week.json if the dailies API misses.

Never commit tokens to git or ship them in the app binary.

Screen map

Screen	GridStats role
Connect	Nav only
Profile	Worker `/api/racer/:psn` + deep link
Sport Mode	Worker `/api/sport/week`
Garage	CDN thumbs; bundled names; live class on detail
Tracks	Bundled art; optional CDN fallback
Race HUD / Audio / Setup	None

Ops

/api/health — includes gridstatsTokenConfigured (boolean only)
/api/sport/week
/api/racer/<public-id>
/api/assets/regions — live with Worker token
Upstream API docs

Home · Architecture · Markdown on GitHub