Configuration

Configuration

All settings live in config.json at the project root (git-ignored — it can hold a private webhook URL or Telegram token). It's auto-created from defaults on first run; config.example.json is provided for reference. Everything here is also editable from the app's Settings tab/page — you rarely need to hand-edit the file.

Full reference

{
  "language": "en",                  // "en" | "zh-Hant" | "zh-Hans" | "ja" | "ko"
  "regions": ["Global"],              // see Regions below
  "source": "leekduck",               // "leekduck" (default) | "blog"
  "refresh_interval_minutes": 60,     // background fetch interval (APScheduler)
  "theme": "midnight_blue",           // "midnight_blue"/"dark" (default) | "light"/"paper_light"
  "database_path": "data/poketrack.db",
  "notifications": true,              // desktop/in-app alerts for new events
  "webhook_url": "",                  // POST new-event alerts here
  "webhook_secret": "",               // HMAC-SHA256 signing key for webhook POSTs
  "favorite_types": [],               // starred event types
  "notify_favorites_only": false,     // only alert for new events of favorited types
  "remind_before_minutes": 15,        // event-start reminder lead time; 0 = off
  "telegram_bot_token": "",
  "telegram_chat_id": "",
  "time_format": "24h",               // "24h" | "12h"
  "display_timezone": "",             // "" = local; or an IANA name, e.g. "Asia/Taipei"
  "close_to_tray": false,             // desktop: minimize to tray instead of quitting
  "prune_after_days": 45,             // drop events that ended more than N days ago
  "web": {
    "host": "127.0.0.1",
    "port": 5000,
    "debug": false
  }
}

Missing keys are always filled in from defaults, so partial/older config files upgrade in place without breaking.

Regions

Available: Global, North America, South America, Europe, Asia, Oceania, Africa.

The ScrapedDuck feed isn't region-tagged, so PokéTrack infers a region from the event name/heading using an ordered keyword map in data/regions_map.json (e.g. Safari Zones / GO Tour stops map to their city/continent). Anything that matches no keyword stays Global and shows for everyone. Selecting a region (e.g. Asia) shows Global + Asia — Global events are always relevant. Extend the keyword map freely as new regional events appear; no code changes needed (see Contributing).

Webhooks

Set webhook_url to receive a POST whenever new events appear in your selected regions (and, if notify_favorites_only is on, only for favorited event types). The payload shape is auto-detected from the URL:

URL contains	Format sent
discord.com/api/webhooks/…	Discord { content, embeds[] }
hooks.slack.com/…	Slack { text }
anything else	Generic { content, text, title, events[] }

Signing (optional): set webhook_secret and every POST carries an X-PokeTrack-Signature: sha256=<hex> header — an HMAC-SHA256 of the exact request body, keyed by your secret. Verify it server-side before trusting the payload, e.g. (Python):

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Settings has a Send test button to verify your URL works before relying on it.

Event reminders

Separate from the new-event webhook/notification triggers above, remind_before_minutes fires a one-time desktop/webhook/Telegram alert a given number of minutes before an event starts (default 15; 0 disables it). This runs off its own 1-minute scheduler check, independent of refresh_interval_minutes, and honours the region filter and notify_favorites_only the same way new-event alerts do.

Theme

theme selects the shared palette both UIs read from poketrack/gui/theme.py: the default Midnight Blue dark palette, or the Paper light palette ("light"; "paper_light" is also accepted). Switching in Settings rebuilds the desktop UI in place and, on the web, is persisted client-side and applied before first paint (no flash of the wrong theme).

Telegram

Set telegram_bot_token (from @BotFather) and telegram_chat_id (your user/group/channel chat ID) to get alerts via a Telegram bot message, on the same triggers as webhooks.

Time display

• time_format: 24h (default) or 12h.
• display_timezone: leave empty to show local system time, or set an IANA timezone name (e.g. America/New_York, Europe/London, Asia/Tokyo) to always display times in that zone regardless of the machine's local timezone. Source event times are timezone-naive local values internally; an invalid timezone name falls back to local time rather than erroring.

Data source

• leekduck (default) — the structured ScrapedDuck JSON feed, mirroring Leek Duck's events page. Rich data: bosses, promo codes, spawn/research flags.
• blog — best-effort HTML scrape of the official Pokémon GO news page. Lighter-weight (title + link only) but doesn't depend on the community mirror; useful as a fallback if the primary feed is ever unreachable.

Import / export

Settings → Export config downloads your current config.json as JSON; Import config deep-merges a previously exported file back in (unknown keys are kept, known keys overwritten) and immediately re-applies anything that affects a running component (language, scheduler interval). Useful for moving settings between the desktop and web UI, or between machines.

Internationalisation (languages.json)

Every UI string lives in the repo-root languages.json, grouped by language then by dotted section key:

{ "en": { "events": { "view_details": "View Details" } } }

Looked up via service.t("events.view_details"), with graceful fallback: current language → English → the key itself — so a missing translation degrades visibly but never crashes the UI. See Contributing for how to add a new language.