repository·master·Indexed 42 days ago
https://github.com/henrygd/ncaa-apiA free API providing consumable JSON data mirrored from ncaa.com, covering scores, stats, rankings, standings, schedules, and news. Built with ElysiaJS, it features automatic caching, OpenAPI support, and the ability to be self-hosted via Docker. Version 3.2.0.
To host your own reliable instance of the API, you can use Docker. The application will be available at http://localhost:3000 by default.
You can use the provided docker-compose.yml or run the container directly with the following command:
docker run --rm -p 3000:3000 henrygd/ncaa-apiThe NCAA API allows you to fetch consumable JSON data from ncaa.com. To use it, make a GET request using the same path as the corresponding URL on the official ncaa.com website.
Rate Limiting: The public demo API is limited to 5 requests per second per IP.
Supported URL Parameters:
page: The page number to retrieve. Defaults to 1.# Example: Fetching scoreboard data
# If the website is https://www.ncaa.com/scoreboard/football/fbs/2023/13/all-conf
# Use the path:
GET /scoreboard/football/fbs/2023/13/all-confThis project is built using ElysiaJS. To run the application in a development environment, use bun.
# Start the development server
bun run dev
# Run tests
bun testThe NCAA API is an Elysia-based web server that provides structured JSON data for NCAA sports, including scores, stats, standings, and more. It acts as a proxy and parser for official NCAA data sources.
Key features include:
NCAA_HEADER_KEY environment variable is set, all requests must include the x-ncaa-key header matching that value.import { app } from './src/index'; // If using as a module
// The server runs on port 3000 by defaultIf you are hosting your own instance, you can restrict access by requiring a specific custom header in all requests.
NCAA_HEADER_KEY environment variable to your desired secret value during deployment.x-ncaa-key with that value in your API requests.You can deploy the NCAA API as a containerized service using Docker Compose. The service runs on port 3000 by default. The image used is henrygd/ncaa-api.
services:
app:
image: 'henrygd/ncaa-api'
container_name: 'ncaa-api'
restart: 'unless-stopped'
ports: ['3000:3000']The NCAA_HEADER_KEY environment variable is an optional setting that can be used to pass a custom header value to the API service. This is configured within the app service in your docker-compose.yml file.
services:
app:
environment:
- NCAA_HEADER_KEY=custom-header-valueThe following routes are available for fetching NCAA data. Most routes follow the structure of the official ncaa.com URLs.
### Scoreboard
`GET /scoreboard/{sport}/{division}/{year}/{week}/{conf}`
### Stats
`GET /stats/{sport}/{division}/{period}/team/{team_id}`
`GET /stats/{sport}/{division}/{period}/individual/{player_id}`
### Rankings
`GET /rankings/{sport}/{division}/{provider}`
### Standings
`GET /standings/{sport}/{division}`
### Game Details
`GET /game/{game_id}` (General info)
`GET /game/{game_id}/boxscore` (Box score)
`GET /game/{game_id}/play-by-play` (Play by play)
`GET /game/{game_id}/scoring-summary` (Scoring summary)
`GET /game/{game_id}/team-stats` (Team stats)
### History
`GET /history/{sport}/{event}`
### Schedule
`GET /schedule/{sport}/{division}/{year}/{month}`
*Note: Football uses `YYYY`, while basketball/hockey use `YYYY/MM`.*
### Brackets
`GET /brackets/{sport}/{division}/{year}`
### News
`GET /news/{sport}/{division}` (Returns parsed RSS in JSON)
### Schools Index
`GET /schools-index` (List of all schools)
### Logos
`GET /logo/{school_slug}.svg`
`GET /logo/{school_slug}.svg?dark=true` (Dark background version)The convertToOldFormat function transforms data from the new NCAA GraphQL endpoint into a legacy format used by older versions of the API.
It performs several key tasks:
gameState values (e.g., 'F' to 'final', 'P' to 'pre', 'I' to 'live').data.ncaa.com endpoint to fill in missing fields like fullName, description, and conferenceName.startTime into a human-readable string (e.g., "12:00PM ET").inputMD5Sum of the games data for backwards compatibility.Parameters:
newData: The GraphQLResponse from fetchGqlScoreboard.sport: The sport string.division: The division string.date: The date string.year: The year as a number.Returns: An object containing inputMD5Sum, instanceId, updated_at, and an array of games in the legacy structure.
import { fetchGqlScoreboard, convertToOldFormat } from './scoreboard/scoreboard';
const newData = await fetchGqlScoreboard(params);
const oldFormat = await convertToOldFormat(
newData,
'football',
'd1',
'2024-11-23',
2024
);Access specific game data using a game ID.
Base Path: /game/:id
Available Sub-routes:
GET /:id: General game details.GET /:id/boxscore: Team boxscore statistics.GET /:id/play-by-play: Play-by-play event data.GET /:id/scoring-summary: Summary of scoring events.GET /:id/team-stats: Detailed team statistics.Response: JSON object containing the requested game data.
Use fetchPlayoffScoreboard to retrieve a combined set of contests from all college football playoff weeks (weeks 16 through 20). This function accepts baseParams that include all required NewScoreboardParams except for the week property, which it iterates through internally.
import { fetchPlayoffScoreboard } from './scoreboard/scoreboard';
const playoffData = await fetchPlayoffScoreboard({
sport: 'football',
division: 'd1',
// ... other NewScoreboardParams excluding 'week'
});Access specific details for a single game using its unique ID.
Endpoints:
/game/{id} - Returns general information about a game./game/{id}/boxscore - Returns the game boxscore./game/{id}/play-by-play - Returns the play-by-play log./game/{id}/scoring-summary - Returns a summary of scoring events./game/{id}/team-stats - Returns statistics for the teams involved in the game.Note: Due to upstream changes, some seasons may not return data for game subroutes (boxscore, play-by-play, etc.).
GET /game/{id}
GET /game/{id}/boxscore
GET /game/{id}/play-by-play
GET /game/{id}/scoring-summary
GET /game/{id}/team-stats