# Baseball Data API manual The whole API in one file, generated from the API's own registry. Operated by DeveloperData.net. Times are UTC; a game's date is its day at the ground. ## Getting access Every account has one key, made when the account is made. Send it on every call in one of two ways: ``` curl https://api.baseballapi.net/v1/leagues -H "X-API-Key: YOUR_KEY" curl https://api.baseballapi.net/v1/leagues -H "Authorization: Bearer YOUR_KEY" ``` A key in the address (`?key=`) is refused with a 400. ## Plans and limits - **Free key:** 10 calls a minute, 50 a day (reset at 00:00 UTC), games from yesterday on. - **Live:** 60 calls a minute, 10000 a day (reset at 00:00 UTC). - **Archive:** 120 calls a minute, 50000 a day (reset at 00:00 UTC). - **Complete:** 300 calls a minute, 250000 a day (reset at 00:00 UTC). Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-Quota-Remaining`. `GET /v1/usage` shows your own figures and does not count. ## Answers Every answer is `{"data": ..., "meta": {...}}`, or on failure `{"error": {"code", "message", "docs"}}`. An empty list is a 200 with `meta.count` 0. Lists take `page` (from 1) and `per_page`; `meta` carries `total`, `total_pages`, `next_page` and `prev_page`, and game lists also `next_cursor` to read on. | Code | HTTP | Meaning | |---|---|---| | `bad_request` | 400 | a value was not what was expected | | `unauthorized` | 401 | no key, or one that is not active | | `upgrade_required` | 403 | not on your plan | | `not_found` | 404 | no such thing | | `method_not_allowed` | 405 | wrong method | | `unknown_parameter` | 422 | a parameter that is not allowed (the answer lists the allowed ones) | | `rate_limited` | 429 | too fast: slow down | | `quota_exceeded` | 429 | today's calls are used | | `server_error` | 500 | our side; it has been logged | ## Endpoints ### Account #### `GET /v1/usage` Your key's plan, calls today, limits, when they reset, and the days your plan can read. Not counted against your allowance. On the free key. Returns: - `plan`: string: the plan's name - `calls_today`: integer: calls counted today (UTC) - `per_day`: integer or null: calls allowed a day - `per_minute`: integer or null: calls allowed a minute - `resets_at`: string: when today's allowance resets, ISO 8601 UTC - `earliest_date`: string or null: the earliest game day this plan can read (null: every season) ### Leagues #### `GET /v1/leagues` Every league we hold, with its seasons and how many of its games carry each part of the record. On the free key. Returns: - `league`: string: the league's slug, used in every league address (/v1/{league}/...) - `name`: string: the league's name - `full_name`: string: a longer description - `country`: string: the country's name - `country_code`: string: ISO 3166 alpha-2, or INT for international tournaments - `first_season`: integer or null: the first season held - `last_season`: integer or null: the latest season held - `seasons`: integer: seasons held - `games`: integer or null: games held one by one (null where the league is held as team seasons) - `team_seasons`: integer or null: team seasons held, where the league is held that way - `with_line_score`: integer or null: games with runs by inning - `with_box_score`: integer or null: games with batting and pitching lines - `with_play_by_play`: integer or null: games with every plate appearance - `with_pitch_data`: integer or null: games with each pitch recorded - `with_weather`: integer or null: games with the weather at or near first pitch - `resting`: boolean: true while the league is between seasons - `checked_at`: string or null: when we last checked for new games, ISO 8601 UTC ### Games #### `GET /v1/{league}/games` Games in a league on a day or across a range of days, with final scores. On the free key. Parameters: - `date` (date): one day, YYYY-MM-DD, or today or yesterday (the day at the ground). The default when no dates are sent is today. - `from` (date): first day of a range (with to; at most 366 days) - `to` (date): last day of a range (with from) - `page` (integer): page number, from 1 - `per_page` (integer): games a page, 50 unless set, at most 200 - `cursor` (string): the next_cursor from the previous answer, to read on Returns: - `id`: string: the game's id (gm_...) - `league`: string: the league's slug - `season`: integer: the season (a winter league's season is the year it starts) - `date`: string: the day at the ground, YYYY-MM-DD - `stage`: string: regular, postseason, all_star, exhibition or other - `status`: string: final, scheduled, in_progress, postponed, suspended or cancelled - `start_local`: string or null: first pitch at the ground, HH:MM - `start_utc`: string or null: first pitch in UTC, ISO 8601 - `away`: object: name and runs (runs null until final) - `home`: object: name and runs (runs null until final) - `innings`: integer or null: innings played - `venue`: string or null: the ground - `checks`: 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 #### `GET /v1/{league}/games/{id}` One game with its line score, the weather at the ground and the umpires, where held. On the free key. Returns: - `id`: string: the game's id (gm_...) - `league`: string: the league's slug - `season`: integer: the season (a winter league's season is the year it starts) - `date`: string: the day at the ground, YYYY-MM-DD - `stage`: string: regular, postseason, all_star, exhibition or other - `status`: string: final, scheduled, in_progress, postponed, suspended or cancelled - `start_local`: string or null: first pitch at the ground, HH:MM - `start_utc`: string or null: first pitch in UTC, ISO 8601 - `away`: object: name and runs (runs null until final) - `home`: object: name and runs (runs null until final) - `innings`: integer or null: innings played - `venue`: string or null: the ground - `checks`: 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`: object or null: away and home, each with innings (runs by inning; null for an inning not batted), runs, hits and errors - `weather`: 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`: array or null: position and name of each umpire #### `GET /v1/results/yesterday` Every finished game from yesterday in every league, newest league first. On the free key. Returns: - `id`: string: the game's id (gm_...) - `league`: string: the league's slug - `season`: integer: the season (a winter league's season is the year it starts) - `date`: string: the day at the ground, YYYY-MM-DD - `stage`: string: regular, postseason, all_star, exhibition or other - `status`: string: final, scheduled, in_progress, postponed, suspended or cancelled - `start_local`: string or null: first pitch at the ground, HH:MM - `start_utc`: string or null: first pitch in UTC, ISO 8601 - `away`: object: name and runs (runs null until final) - `home`: object: name and runs (runs null until final) - `innings`: integer or null: innings played - `venue`: string or null: the ground - `checks`: 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 ### Parks #### `GET /v1/parks` Every major-league ground held, with its first and last game; or the grounds used in one season. On the free key. Parameters: - `season` (integer): only the grounds used in this season - `page` (integer): page number, from 1 - `per_page` (integer): parks a page, 50 unless set, at most 200 Returns: - `id`: string: the park's id (pk_...) - `name`: string or null: the ground's name - `city`: string or null - `region`: string or null: state or province - `first_game`: string or null: first game held there, YYYY-MM-DD - `last_game`: string or null: last game held there, YYYY-MM-DD (null while in use) #### `GET /v1/parks/{id}` One ground, and season by season its games, runs per game and park factor. On the free key. Returns: - `id`: string: the park's id (pk_...) - `name`: string or null - `city`: string or null - `region`: string or null - `first_game`: string or null - `last_game`: string or null - `seasons`: array: season, games, first_game, last_game, runs_per_game, park_factor (the home clubs' factor there, weighted by home games) ### Players #### `GET /v1/players` Find people in the US majors and Negro Leagues by name: players, managers, coaches and umpires. On the free key. Parameters: - `name` (string, required): one or more words; each must start the last name or a first name - `page` (integer): page number, from 1 - `per_page` (integer): people a page, 50 unless set, at most 200 Returns: - `id`: string: the person's id (pl_...) - `name`: string or null: the name they were known by - `last_name`: string or null - `roles`: array: role (player, coach, manager or umpire), first_game and last_game in that role #### `GET /v1/players/{id}` One person: names, birth and death, bats and throws, height and weight, and each role with its dates. On the free key. Returns: - `id`: string - `name`: string or null - `last_name`: string or null - `roles`: array, as in the search - `full_name`: string or null - `birth_name`: string or null - `birth_date`: string or null: YYYY-MM-DD - `birth_place`: object: city, region, country - `death_date`: string or null - `death_place`: object or null: city, region, country - `bats`: string or null: right, left or both - `throws`: string or null: right, left or both - `height_cm`: integer or null - `weight_kg`: integer or null - `hall_of_fame`: boolean ### Games #### `GET /v1/{league}/games/{id}/boxscore` Batting and pitching lines for both sides of one game, where held. On the free key. Returns: - `game_id`: string: the game's id - `away`: 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`: object: the same for the home side - `held`: boolean: false when no box score is held for this game (the lists are then empty) #### `GET /v1/{league}/games/{id}/plays` Every plate appearance of one game in order, with the pitches where they were recorded. On the free key. Returns: - `seq`: integer: order in the game, from 1 - `inning`: integer - `half`: string: top or bottom - `batter`: object: id (pl_..., where held) and name - `pitcher`: object: id and name - `outs_before`: integer or null - `balls`: integer or null - `strikes`: integer or null: the final count - `pitches`: array or null: each pitch as ball, called_strike, swinging_strike, foul, in_play, hit_by_pitch or other - `result`: string: single, double, triple, home_run, walk, intentional_walk, strikeout, hit_by_pitch, out, error, fielders_choice, sacrifice, catcher_interference or other - `batted_ball`: string or null: ground, line, fly or popup - `runs`: integer: runs scored on the play - `rbi`: integer or null - `away_score`: integer or null - `home_score`: integer or null: the score after the play ## Leagues The league slugs used in `/v1/{league}/...`: `mlb`, `negro`, `kbo`, `cpbl`, `lmp`, `lvbp`, `cuba`, `germany`, `czech`, `intl`. `GET /v1/leagues` lists them with what each holds.