{
  "name": "EGHC Match Centre API",
  "description": "Read-only JSON API over an England Hockey results warehouse: every adult competition in England back to season 2022-23. The website is client-rendered, so this API - not the HTML - is the machine-readable surface.",
  "club": "East Grinstead Hockey Club",
  "dataSource": "England Hockey Data Warehouse, crawled nightly into Cloudflare D1.",
  "coverage": {
    "seasons": "2022-23 to 2026-27",
    "scope": "All adult competitions nationally. Junior and school competitions are excluded.",
    "note": "Team ids are stable across seasons; competition ids are not."
  },
  "conventions": {
    "ids": "All ids are lowercase UUIDs. Requests are case-insensitive.",
    "dates": "ISO 8601. A fixtureTime of \"00:00\" means the kick-off time is not yet published.",
    "byes": "Fixtures with isBye true are not real matches; exclude them when aggregating.",
    "errors": "Non-2xx responses return { error: string }.",
    "auth": "None required. All endpoints are public and read-only."
  },
  "ratings": {
    "method": "Massey least-squares over every result, recent seasons weighted more heavily (half-life 1.5 seasons).",
    "margins": "Capped at 6 goals so one heavy defeat does not dominate.",
    "scopes": {
      "competition": "Within one division and season.",
      "global": "Every result at once; the scale the difficulty badge uses.",
      "season": "Cumulative snapshot as of each season, for trajectories."
    },
    "caveat": "Difficulty is normalised by the rating spread of the fixture's own division, not a national spread, so \"hard\" means hard for that league."
  },
  "endpoints": [
    {
      "path": "/api/seasons",
      "method": "GET",
      "summary": "Seasons the club has fixtures for, newest first.",
      "parameters": [],
      "returns": "{ current: seasonId, seasons: [{ id, description, year, games, results, isCurrent }] }",
      "url": "https://eghc-matches.pages.dev/api/seasons"
    },
    {
      "path": "/api/matches",
      "method": "GET",
      "summary": "Current-season fixtures and results, live from the England Hockey feed.",
      "parameters": [],
      "returns": "{ nextMatchDay, matchDays: [{ matchDay, competitions: [{ competitionId, competitionName, fixtures: [...] }] }] }",
      "note": "Current season only. Use /api/season for archived seasons.",
      "url": "https://eghc-matches.pages.dev/api/matches"
    },
    {
      "path": "/api/season",
      "method": "GET",
      "summary": "One season of the club's fixtures and results, from the warehouse.",
      "parameters": [
        {
          "name": "season",
          "in": "query",
          "required": true,
          "type": "uuid",
          "description": "Season id from /api/seasons"
        }
      ],
      "returns": "{ season, competitions: [{ id, name }], fixtures: [{ id, fixtureDate, isHome, isResult, homeScore, awayScore, homeTeam, awayTeam, ... }] }",
      "url": "https://eghc-matches.pages.dev/api/season"
    },
    {
      "path": "/api/table",
      "method": "GET",
      "summary": "Official league table, proxied live from England Hockey.",
      "parameters": [
        {
          "name": "competition",
          "in": "query",
          "required": true,
          "type": "uuid"
        }
      ],
      "returns": "{ competitionId, table: [{ position, teamName, played, won, drawn, lost, goalsFor, goalsAgainst, goalDifference, points, adjustment }] }",
      "note": "Includes official points adjustments. Only works for competitions currently running, and only for competitions this club plays in.",
      "url": "https://eghc-matches.pages.dev/api/table"
    },
    {
      "path": "/api/standings",
      "method": "GET",
      "summary": "League table computed from stored results. Works for any competition in the archive.",
      "parameters": [
        {
          "name": "competition",
          "in": "query",
          "required": true,
          "type": "uuid"
        }
      ],
      "returns": "{ competitionId, competitionName, season, computed: true, table: [...] }",
      "note": "Cannot know about points deductions applied by England Hockey, so may differ from the official table by exactly that adjustment.",
      "url": "https://eghc-matches.pages.dev/api/standings"
    },
    {
      "path": "/api/stats",
      "method": "GET",
      "summary": "Per-team history: season-by-season record, form, home/away split, rating trajectory, optional head-to-head.",
      "parameters": [
        {
          "name": "team",
          "in": "query",
          "required": true,
          "type": "uuid"
        },
        {
          "name": "opponent",
          "in": "query",
          "required": false,
          "type": "uuid",
          "description": "Adds a headToHead block"
        }
      ],
      "returns": "{ team, seasons: [...], form: { last6, ppgLast6, ppgPrevious6 }, homeAway, trajectory, headToHead }",
      "note": "Works for any team in the warehouse, not only this club.",
      "url": "https://eghc-matches.pages.dev/api/stats"
    },
    {
      "path": "/api/matchup",
      "method": "GET",
      "summary": "Why a fixture has the difficulty it does: both sides rated, ranked, their form, head-to-head and common opponents.",
      "parameters": [
        {
          "name": "team",
          "in": "query",
          "required": true,
          "type": "uuid"
        },
        {
          "name": "opponent",
          "in": "query",
          "required": true,
          "type": "uuid"
        },
        {
          "name": "competition",
          "in": "query",
          "required": true,
          "type": "uuid"
        }
      ],
      "returns": "{ competition, difficulty: { band, label, gap, ratingDifference, spread, ourRank, theirRank }, us, them, headToHead, commonOpponents, unrated }",
      "note": "Works for any pair of teams in the warehouse.",
      "url": "https://eghc-matches.pages.dev/api/matchup"
    },
    {
      "path": "/api/difficulty",
      "method": "GET",
      "summary": "Ratings for every team sharing a division with this club this season, for the fixture difficulty badge.",
      "parameters": [],
      "returns": "{ ready, season, spreads: { competitionId: number }, labels, ratings: { teamId: { rating, games, name } } }",
      "url": "https://eghc-matches.pages.dev/api/difficulty"
    },
    {
      "path": "/api/schedule.jsonld",
      "method": "GET",
      "summary": "Schema.org SportsEvent feed of the current season, for structured-data consumers.",
      "parameters": [
        {
          "name": "season",
          "in": "query",
          "required": false,
          "type": "uuid",
          "description": "Defaults to the current season"
        }
      ],
      "returns": "application/ld+json ItemList of SportsEvent",
      "url": "https://eghc-matches.pages.dev/api/schedule.jsonld"
    }
  ],
  "documentation": "https://eghc-matches.pages.dev/llms.txt"
}