# MaxPreps — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access high school sports data from MaxPreps. Search for schools, retrieve team rosters and schedules, look up athlete profiles, and browse national or state rankings across all sports.

**Category:** Sports | **Website:** [maxpreps.com/](https://maxpreps.com/) | **Docs:** [parse.bot/marketplace/1d510b08-d5bf-481d-aa00-82f8b510e6dd/maxpreps-com-api](https://parse.bot/marketplace/1d510b08-d5bf-481d-aa00-82f8b510e6dd/maxpreps-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_athlete_profile

Get detailed athlete profile including career history, timeline, prospect report, and club teams. Use the career_id from the roster endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `career_id` | string | Yes | The career ID for the athlete from get_team_roster results (e.g., '3gae9h76ao6l5') |
| `path` | string | Yes | The athlete profile path from get_team_roster results (e.g., '/va/mouth-of-wilson/oak-hill-academy-warriors/athletes/donovan-williams-ii/') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_athlete_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"career_id":"<string>","path":"<string>"}'
```

### get_live_and_upcoming_games

Get live scores and upcoming scheduled games for a specific sport and state. Returns the next set of games (typically the nearest game day) with team names, records, scores (when available), game status (live/upcoming/final), and links to game details. For live games, additional detail fields (period, clock, possession, last_updated) are returned when MaxPreps provides them. An optional school filter narrows results to games involving that school. Requires a state code and sport.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `gender` | string | No | Gender category: 'boys' or 'girls' |
| `school` | string | No | Optional school filter. Accepts an exact school name (e.g., 'Buna'), a school path (e.g., '/tx/buna/buna-cougars/'), or a school_id UUID. When provided, only games involving the specified school are returned. |
| `sport` | string | Yes | Sport name (e.g., 'football', 'basketball', 'baseball', 'soccer', 'volleyball', 'lacrosse', 'ice-hockey', 'water-polo', 'softball', 'field-hockey', 'flag-football', 'beach-volleyball') |
| `state` | string | Yes | Two-letter US state code (e.g., 'tx', 'ca', 'fl') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_live_and_upcoming_games \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gender":"<string>","school":"<string>","sport":"<string>","state":"<string>"}'
```

### get_rankings

Get national or state rankings for a sport. Returns ranked list of schools with records and movement indicators.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sport` | string | Yes | The sport name (e.g., 'basketball', 'football', 'baseball', 'volleyball') |
| `state` | string | No | Two-letter state code for state rankings (e.g., 'va', 'ca', 'tx') or 'national' for national rankings |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_rankings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sport":"<string>","state":"<string>"}'
```

### get_scoretracker

Get scoretracker data for a specific game given its MaxPreps game URL. Returns live scoring updates, team scores, per-period scoring breakdown, game clock, possession, down-and-distance, and field position when available from the Scoretracker tab. For upcoming games where no scorekeeper has checked in, score and game state fields will be null. Requires the full game URL including the 'c' query parameter with the contest ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `game_url` | string | Yes | The full MaxPreps game URL including the contest ID query parameter (e.g., 'https://www.maxpreps.com/ca/football/game/centennial-corona-vs-mater-dei-santa-ana/8-22-2024/?c=658524d0-3019-4c2c-ae9b-019769238aac') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_scoretracker \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"game_url":"<string>"}'
```

### get_scoretracker_by_id

Get live scoretracker data for a game by its internal game ID (qwixCoreGameId) using a single upstream API request. Returns team names, school IDs, scores, per-period scoring breakdown, game period, clock, possession, and football-specific fields (down/distance, field position) when available. For games where no scorekeeper has checked in, the upstream returns an error. The game ID can be obtained from the get_scoretracker endpoint's response or from the game page's embedded contest context.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `contest_id` | string | Yes | The MaxPreps internal game ID (qwixCoreGameId UUID, e.g., '226d1be2-5c52-477c-a4c7-30a71f8b1e14'). This is the Qwixcore scoring system game identifier, obtainable from the game page context. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_scoretracker_by_id \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contest_id":"<string>"}'
```

### get_team_roster

Get the roster for a specific team and season. Returns player details including name, jersey number, position, height, grade, and links to athlete profiles.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | The school/team path including sport, from search_schools results with sport appended (e.g., '/ca/santa-ana/mater-dei-monarchs/football/') |
| `season` | string | No | The school year season in YY-YY format (e.g., '24-25', '23-24') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_team_roster \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"<string>","season":"<string>"}'
```

### get_team_schedule

Get the schedule and results for a team in a given season. Returns parsed contest data with dates, opponents, scores, win/loss results, game URLs, and contest IDs that can be passed to scoretracker endpoints. Each contest's home_team and away_team includes school identity metadata (school_name, school_url, mascot, school_color1, school_color2, school_color3). The team object also includes these snake_case identity fields alongside the upstream camelCase fields.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | The school/team path including sport (e.g., '/ca/santa-ana/mater-dei-monarchs/football/') |
| `season` | string | No | The school year season in YY-YY format |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/get_team_schedule \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"<string>","season":"<string>"}'
```

### search_schools

Search for schools by name or query. Returns matching schools with their IDs, locations, mascots, and paths for use in other endpoints.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | School name or search query (e.g., 'Oak Hill Academy', 'Mater Dei') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maxpreps-com-api-1d510b08/search_schools \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```