{ "openapi": "3.1.0", "info": { "title": "Baseball Data API", "version": "1", "description": "Baseball data: games, line scores, parks, players and coverage across the US majors, the minors and leagues abroad. Operated by DeveloperData.net.", "termsOfService": "https://baseballapi.net/terms", "contact": { "url": "https://baseballapi.net/support" } }, "servers": [ { "url": "https://api.baseballapi.net" } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "paths": { "/v1/usage": { "get": { "operationId": "my_usage", "summary": "Your key's plan, calls today, limits, when they reset, and the days your plan can read. Not counted against your allowance.", "tags": [ "Account" ], "parameters": [], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "plan": { "description": "string: the plan's name" }, "calls_today": { "description": "integer: calls counted today (UTC)" }, "per_day": { "description": "integer or null: calls allowed a day" }, "per_minute": { "description": "integer or null: calls allowed a minute" }, "resets_at": { "description": "string: when today's allowance resets, ISO 8601 UTC" }, "earliest_date": { "description": "string or null: the earliest game day this plan can read (null: every season)" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/leagues": { "get": { "operationId": "list_leagues", "summary": "Every league we hold, with its seasons and how many of its games carry each part of the record.", "tags": [ "Leagues" ], "parameters": [], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "league": { "description": "string: the league's slug, used in every league address (/v1/{league}/...)" }, "name": { "description": "string: the league's name" }, "full_name": { "description": "string: a longer description" }, "country": { "description": "string: the country's name" }, "country_code": { "description": "string: ISO 3166 alpha-2, or INT for international tournaments" }, "first_season": { "description": "integer or null: the first season held" }, "last_season": { "description": "integer or null: the latest season held" }, "seasons": { "description": "integer: seasons held" }, "games": { "description": "integer or null: games held one by one (null where the league is held as team seasons)" }, "team_seasons": { "description": "integer or null: team seasons held, where the league is held that way" }, "with_line_score": { "description": "integer or null: games with runs by inning" }, "with_box_score": { "description": "integer or null: games with batting and pitching lines" }, "with_play_by_play": { "description": "integer or null: games with every plate appearance" }, "with_pitch_data": { "description": "integer or null: games with each pitch recorded" }, "with_weather": { "description": "integer or null: games with the weather at or near first pitch" }, "resting": { "description": "boolean: true while the league is between seasons" }, "checked_at": { "description": "string or null: when we last checked for new games, ISO 8601 UTC" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/{league}/games": { "get": { "operationId": "find_games", "summary": "Games in a league on a day or across a range of days, with final scores.", "tags": [ "Games" ], "parameters": [ { "name": "league", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "mlb", "negro", "kbo", "cpbl", "lmp", "lvbp", "cuba", "germany", "czech", "intl" ] }, "description": "the league's slug, from /v1/leagues" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "description": "YYYY-MM-DD, or today or yesterday", "pattern": "^(\\d{4}-\\d{2}-\\d{2}|today|yesterday)$" }, "description": "one day, YYYY-MM-DD, or today or yesterday (the day at the ground). The default when no dates are sent is today." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "YYYY-MM-DD, or today or yesterday", "pattern": "^(\\d{4}-\\d{2}-\\d{2}|today|yesterday)$" }, "description": "first day of a range (with to; at most 366 days)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "YYYY-MM-DD, or today or yesterday", "pattern": "^(\\d{4}-\\d{2}-\\d{2}|today|yesterday)$" }, "description": "last day of a range (with from)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 }, "description": "page number, from 1" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "games a page, 50 unless set, at most 200" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "the next_cursor from the previous answer, to read on" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string: the game's id (gm_...)" }, "league": { "description": "string: the league's slug" }, "season": { "description": "integer: the season (a winter league's season is the year it starts)" }, "date": { "description": "string: the day at the ground, YYYY-MM-DD" }, "stage": { "description": "string: regular, postseason, all_star, exhibition or other" }, "status": { "description": "string: final, scheduled, in_progress, postponed, suspended or cancelled" }, "start_local": { "description": "string or null: first pitch at the ground, HH:MM" }, "start_utc": { "description": "string or null: first pitch in UTC, ISO 8601" }, "away": { "description": "object: name and runs (runs null until final)" }, "home": { "description": "object: name and runs (runs null until final)" }, "innings": { "description": "integer or null: innings played" }, "venue": { "description": "string or null: the ground" }, "checks": { "description": "object or null: for MLB games of the season in play, how the final was checked: sources (pages read), sources_agree, line_matches_final (postseason) and delay_minutes (from the score being recorded to our record). For archive MLB games, the trust flag: disputed (true when our own checks found the game's parts disagreeing) and disputes, each with check (runs_vs_team_box, team_box_vs_batters or plays_vs_box), side (away or home) and detail; the record is shown as it is, never corrected. Null for other leagues" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/{league}/games/{id}": { "get": { "operationId": "get_game", "summary": "One game with its line score, the weather at the ground and the umpires, where held.", "tags": [ "Games" ], "parameters": [ { "name": "league", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "mlb", "negro", "kbo", "cpbl", "lmp", "lvbp", "cuba", "germany", "czech", "intl" ] }, "description": "the league's slug, from /v1/leagues" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "an id from a list answer" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string: the game's id (gm_...)" }, "league": { "description": "string: the league's slug" }, "season": { "description": "integer: the season (a winter league's season is the year it starts)" }, "date": { "description": "string: the day at the ground, YYYY-MM-DD" }, "stage": { "description": "string: regular, postseason, all_star, exhibition or other" }, "status": { "description": "string: final, scheduled, in_progress, postponed, suspended or cancelled" }, "start_local": { "description": "string or null: first pitch at the ground, HH:MM" }, "start_utc": { "description": "string or null: first pitch in UTC, ISO 8601" }, "away": { "description": "object: name and runs (runs null until final)" }, "home": { "description": "object: name and runs (runs null until final)" }, "innings": { "description": "integer or null: innings played" }, "venue": { "description": "string or null: the ground" }, "checks": { "description": "object or null: for MLB games of the season in play, how the final was checked: sources (pages read), sources_agree, line_matches_final (postseason) and delay_minutes (from the score being recorded to our record). For archive MLB games, the trust flag: disputed (true when our own checks found the game's parts disagreeing) and disputes, each with check (runs_vs_team_box, team_box_vs_batters or plays_vs_box), side (away or home) and detail; the record is shown as it is, never corrected. Null for other leagues" }, "line_score": { "description": "object or null: away and home, each with innings (runs by inning; null for an inning not batted), runs, hits and errors" }, "weather": { "description": "object or null: level, temperature_c, dew_point_c, wind_kmh, wind_direction_deg, pressure_hpa, precipitation_mm, day_high_c, day_low_c, sky, station_km" }, "umpires": { "description": "array or null: position and name of each umpire" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/results/yesterday": { "get": { "operationId": "yesterdays_results", "summary": "Every finished game from yesterday in every league, newest league first.", "tags": [ "Games" ], "parameters": [], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string: the game's id (gm_...)" }, "league": { "description": "string: the league's slug" }, "season": { "description": "integer: the season (a winter league's season is the year it starts)" }, "date": { "description": "string: the day at the ground, YYYY-MM-DD" }, "stage": { "description": "string: regular, postseason, all_star, exhibition or other" }, "status": { "description": "string: final, scheduled, in_progress, postponed, suspended or cancelled" }, "start_local": { "description": "string or null: first pitch at the ground, HH:MM" }, "start_utc": { "description": "string or null: first pitch in UTC, ISO 8601" }, "away": { "description": "object: name and runs (runs null until final)" }, "home": { "description": "object: name and runs (runs null until final)" }, "innings": { "description": "integer or null: innings played" }, "venue": { "description": "string or null: the ground" }, "checks": { "description": "object or null: for MLB games of the season in play, how the final was checked: sources (pages read), sources_agree, line_matches_final (postseason) and delay_minutes (from the score being recorded to our record). For archive MLB games, the trust flag: disputed (true when our own checks found the game's parts disagreeing) and disputes, each with check (runs_vs_team_box, team_box_vs_batters or plays_vs_box), side (away or home) and detail; the record is shown as it is, never corrected. Null for other leagues" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/parks": { "get": { "operationId": "find_parks", "summary": "Every major-league ground held, with its first and last game; or the grounds used in one season.", "tags": [ "Parks" ], "parameters": [ { "name": "season", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 }, "description": "only the grounds used in this season" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 }, "description": "page number, from 1" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "parks a page, 50 unless set, at most 200" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string: the park's id (pk_...)" }, "name": { "description": "string or null: the ground's name" }, "city": { "description": "string or null" }, "region": { "description": "string or null: state or province" }, "first_game": { "description": "string or null: first game held there, YYYY-MM-DD" }, "last_game": { "description": "string or null: last game held there, YYYY-MM-DD (null while in use)" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/parks/{id}": { "get": { "operationId": "get_park", "summary": "One ground, and season by season its games, runs per game and park factor.", "tags": [ "Parks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "an id from a list answer" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string: the park's id (pk_...)" }, "name": { "description": "string or null" }, "city": { "description": "string or null" }, "region": { "description": "string or null" }, "first_game": { "description": "string or null" }, "last_game": { "description": "string or null" }, "seasons": { "description": "array: season, games, first_game, last_game, runs_per_game, park_factor (the home clubs' factor there, weighted by home games)" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/players": { "get": { "operationId": "find_players", "summary": "Find people in the US majors and Negro Leagues by name: players, managers, coaches and umpires.", "tags": [ "Players" ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "one or more words; each must start the last name or a first name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000 }, "description": "page number, from 1" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "people a page, 50 unless set, at most 200" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string: the person's id (pl_...)" }, "name": { "description": "string or null: the name they were known by" }, "last_name": { "description": "string or null" }, "roles": { "description": "array: role (player, coach, manager or umpire), first_game and last_game in that role" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/players/{id}": { "get": { "operationId": "get_player", "summary": "One person: names, birth and death, bats and throws, height and weight, and each role with its dates.", "tags": [ "Players" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "an id from a list answer" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "id": { "description": "string" }, "name": { "description": "string or null" }, "last_name": { "description": "string or null" }, "roles": { "description": "array, as in the search" }, "full_name": { "description": "string or null" }, "birth_name": { "description": "string or null" }, "birth_date": { "description": "string or null: YYYY-MM-DD" }, "birth_place": { "description": "object: city, region, country" }, "death_date": { "description": "string or null" }, "death_place": { "description": "object or null: city, region, country" }, "bats": { "description": "string or null: right, left or both" }, "throws": { "description": "string or null: right, left or both" }, "height_cm": { "description": "integer or null" }, "weight_kg": { "description": "integer or null" }, "hall_of_fame": { "description": "boolean" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/{league}/games/{id}/boxscore": { "get": { "operationId": "get_boxscore", "summary": "Batting and pitching lines for both sides of one game, where held.", "tags": [ "Games" ], "parameters": [ { "name": "league", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "mlb", "negro", "kbo", "cpbl", "lmp", "lvbp", "cuba", "germany", "czech", "intl" ] }, "description": "the league's slug, from /v1/leagues" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "an id from a list answer" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "game_id": { "description": "string: the game's id" }, "away": { "description": "object: batting (player, order, position, substitute, pa, ab, r, h, doubles, triples, hr, rbi, bb, ibb, so, hbp, sh, sf, sb, cs, gidp) and pitching (player, started, outs, innings, bf, h, r, er, bb, ibb, so, hr, hbp, wp, bk, pitches, strikes, decision)" }, "home": { "description": "object: the same for the home side" }, "held": { "description": "boolean: false when no box score is held for this game (the lists are then empty)" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/{league}/games/{id}/plays": { "get": { "operationId": "get_plays", "summary": "Every plate appearance of one game in order, with the pitches where they were recorded.", "tags": [ "Games" ], "parameters": [ { "name": "league", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "mlb", "negro", "kbo", "cpbl", "lmp", "lvbp", "cuba", "germany", "czech", "intl" ] }, "description": "the league's slug, from /v1/leagues" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "an id from a list answer" } ], "x-free-key": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "the answer: one object, or a list of them", "x-fields": { "seq": { "description": "integer: order in the game, from 1" }, "inning": { "description": "integer" }, "half": { "description": "string: top or bottom" }, "batter": { "description": "object: id (pl_..., where held) and name" }, "pitcher": { "description": "object: id and name" }, "outs_before": { "description": "integer or null" }, "balls": { "description": "integer or null" }, "strikes": { "description": "integer or null: the final count" }, "pitches": { "description": "array or null: each pitch as ball, called_strike, swinging_strike, foul, in_play, hit_by_pitch or other" }, "result": { "description": "string: single, double, triple, home_run, walk, intentional_walk, strikeout, hit_by_pitch, out, error, fielders_choice, sacrifice, catcher_interference or other" }, "batted_ball": { "description": "string or null: ground, line, fly or popup" }, "runs": { "description": "integer: runs scored on the play" }, "rbi": { "description": "integer or null" }, "away_score": { "description": "integer or null" }, "home_score": { "description": "integer or null: the score after the play" } } }, "meta": { "type": "object", "description": "count, and on lists the paging fields" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "bearer": { "type": "http", "scheme": "bearer" } }, "responses": { "Error": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "upgrade_required", "not_found", "method_not_allowed", "unknown_parameter", "rate_limited", "quota_exceeded", "server_error" ] }, "message": { "type": "string" }, "docs": { "type": "string" } } } } } } } } } } }