# OP.GG LoL AI-readable data reference

This document describes the compact, first-party JSON snapshots exposed for League of Legends summoner profiles and match details. It is a schema and usage reference, not a directory of summoners or matches.

## Discovery

- Short discovery document: `https://op.gg/llms.txt`
- Summoner snapshot pattern: `https://op.gg/{optionalLocale}/lol/summoners/{region}/{gameName}-{tagline}/ai.json`
- Match snapshot pattern: `https://op.gg/{optionalLocale}/lol/summoners/{region}/{gameName}-{tagline}/matches/{gameId}/{createdAtTimestamp}/ai.json`
- The default English path omits `{optionalLocale}/`.

Request a snapshot only after a user or an existing OP.GG page provides the corresponding canonical URL. Do not use these patterns to discover or enumerate accounts.

## Summoner snapshot schema

- `summary`: A compact factual narrative assembled from the fields in the same response.
- `context`: Source, game, locale, region, queue type, and page type.
- `identity`: PUUID, Riot ID components, level, and profile image URL.
- `freshness`: Summoner update time and latest included match time when available.
- `rank`: Ladder position and ranked entries with tier, division, LP, wins, losses, and win rate when available.
- `recentChampions`: Up to five champion statistics. Recent champion statistics are preferred; when those are absent, the same most-champion statistics used by the page metadata are returned.
- `recentGames`: Up to ten included matches with queue, result, champion, position, KDA, CS, OP Score, and placement fields when available.

Illustrative response shape (values are placeholders, not a real account):

```json
{
  "summary": "Factual 3-5 sentence summary derived from this response.",
  "context": {
    "source": "OP.GG",
    "game": "League of Legends",
    "locale": "en",
    "region": "kr",
    "queueType": "SOLORANKED",
    "pageType": "summoner-profile"
  },
  "identity": {
    "puuid": "string",
    "gameName": "string",
    "tagline": "string",
    "riotId": "string#string",
    "level": 0,
    "profileImageUrl": "https://..."
  },
  "freshness": {
    "summonerUpdatedAt": "ISO-8601 timestamp or null",
    "latestGamePlayedAt": "ISO-8601 timestamp or null"
  },
  "rank": {
    "ladderRank": null,
    "ladderTopRatio": null,
    "entries": []
  },
  "recentChampions": [],
  "recentGames": []
}
```

## Match snapshot schema

- `summary`: Result, queue, champion, KDA, CS, build, and team objective facts when present.
- `context`: Source, locale, region, page type, and canonical match page URL.
- `summoner`: Target summoner identity.
- `match`: Match ID, played time, duration, patch, queue, map, average tier, and target result.
- `targetParticipant`: Target participant identity and first-party performance statistics.
- `build`: Champion, items, spells, runes, and augments available in the match payload.
- `teams`: Blue, red, and Arena team participant and objective totals. Missing objective data is represented as `null`, not inferred.

Illustrative response shape (values are placeholders, not a real match):

```json
{
  "summary": "Factual 3-5 sentence summary derived from this response.",
  "context": {
    "source": "OP.GG",
    "game": "League of Legends",
    "locale": "en",
    "region": "kr",
    "pageType": "match-detail",
    "canonicalUrl": "https://op.gg/lol/summoners/{region}/{gameName}-{tagline}/matches/{gameId}/{createdAtTimestamp}"
  },
  "summoner": {},
  "match": {},
  "targetParticipant": {},
  "build": {},
  "teams": {
    "blue": {},
    "red": {},
    "arena": []
  }
}
```

## Freshness and caching

Snapshots are assembled from OP.GG's current first-party server data. Consumers should inspect the response freshness fields instead of assuming that every upstream field was updated at request time.

Successful snapshot responses use `Cache-Control: public, s-maxage=300, stale-while-revalidate=600`. Reuse a cached response during that window instead of repeatedly requesting the same URL. Empty or unavailable fields must not be replaced with inferred rankings, evaluations, or generated game facts.

## Canonical citation rule

Cite the corresponding canonical OP.GG page URL, not the `/ai.json` URL. For match snapshots, use `context.canonicalUrl`. For summoner snapshots, remove the trailing `/ai.json` from the requested snapshot URL while preserving the locale, region, and encoded Riot ID.

## Crawl and rate-limit etiquette

- Do not enumerate summoner or match URLs.
- Do not crawl per-summoner snapshots at high rate or use them to build a bulk player index.
- Fetch only URLs needed for the user's current task and cache successful responses.
- Prefer `llms.txt`, this reference, and canonical pages for general discovery.
- Respect HTTP status codes, cache headers, and backoff after errors.
- No crawler allow/block, robots, WAF, or CDN policy is defined or changed by this document.