Crate mlb_api

Expand description

§The Rust MLB API Wrapper

This project and its author are not affiliated with MLB or any MLB team. This crate wraps the existing MLB Stats API, which is subject to the notice posted at http://gdx.mlb.com/components/copyright.txt.

§Usage

Endpoints are most commonly used using their module’s builder functions.

use mlb_api::sport::SportId;
use mlb_api::request::RequestUrlBuilderExt;
use mlb_api::schedule::{self, ScheduleResponse, ScheduleDate};
 
let response: ScheduleResponse = schedule::request()
    .sport_id(SportId::MLB)
    .build_and_get()
    .await?;
 
let [date]: [ScheduleDate; 1] = response.dates.try_into()?;

Play Streams are the recommended way to process live games

use mlb_api::game::PlayStream;
 
let game: ScheduleGame = ...;
 
PlayStream::new(game.game_id).run(|event, _meta, _data| { ... }).await?;

Use single_stat! for simple stats requests and make your own hydrations for more complicated requests

use mlb_api::single_stat;
use mlb_api::person::{self, PeopleResonse};

let season_hitting = single_stat!( Season + Hitting for 660_271 ).await?;
let sabermetrics_pitching = single_stat!( Sabermetrics + Pitching for 660_271; with |builder| builder.season(2024) ).await?;

person_hydrations! {
    struct PersonDisplayHydrations {
        nicknames,
        stats: { [Season, Sabermetrics] = [Hitting, Pitching] },
    }
}

let response: PeopleResponse = person::request_with_hydrations::<PersonDisplayHydrations>(660_271).await?;

§Endpoints

This API contains wrappers / bindings for all known public MLB API endpoints (unless incomplete), the table of which can be seen below. Additional information can be found at https://github.com/toddrob99/MLB-StatsAPI/wiki/Endpoints (thanks Todd Roberts)

Stars hightlight the most popular and used endpoints

Endpoint	Description
`attendance`	Team attendance data by season
`awards`	List of all awards, Cy Young, MVP, etc.
`conference`	Conferences, like divisions but not
`division`	Names, has a wildcard or not, playoff teams
`draft`	Draft rounds, players, etc.
`live_feed` ⭐	`boxscore`, `linescore`, `plays`, and misc
`diff_patch`	JSON diff patch for live feed
`timestamps`	List of timestamps for game plays & play events
`changes`	Games that underwent scheduling changes (?)
`context_metrics`	Various metrics for game plays & play events
`win_probability`	Win Probability calculations for games
`boxscore`	Boxscore summary for game, includes stats
`content`	Editorial content regarding games
`linescore`	Linescore for games
`plays`	Play by Play Data on a game
`uniforms`	Game Uniforms
`pace`	Average game durations and league stat totals
`home_run_derby`	Home Run Derby stats
`league`	League data, AL, NL, divisions contained, etc.
`all_star`	ASG data
`person` ⭐	A person, lots of data here
`free_agents`	Free agents in any given year
`person_stats`	Player stats for a single game
`jobs`	List of all people with a job, ex: scorer, ump
`jobs::umpire`	List of all umpires
`jobs::datacasters`	List of all datacasters
`jobs::official_scorers`	List of all official scorers
`schedule` ⭐	All games played within a certain date range
`schedule::tied`	All games that ended tied (?)
`schedule::postseason`	Postseason schedule
`schedule::postseason::series`	Postseason series schedule
`season`	Date ranges for season states: reg, post, spring
`sport`	List of sports, MLB, AAA, AA, A+, etc.
`players` ⭐	List of all players in a sport and season
`standings`	Standings information for teams
`stats`	Stats data
`stats::leaders`	League leaders in specific stats
`team` ⭐	Team data
`team::history`	History of a team, such as Brooklyn & LA Dodgers
`team::stats`	Stats for a team
`team::affiliates`	Minor league affiliate teams
`team::alumni`	Alumni for a team
`team::coaches`	List of coaches on a team
`team::personnel`	Personnel on a team
`team::leaders`	Stat leaders per team
`team::roster`	Roster players on a team
`team::uniforms`	Uniforms a team wears
`transactions`	Trades, IL moves, etc.
`venue`	Yankee Stadium, Dodger Stadium, Fenway Park, etc.
`meta`	Metadata endpoints, typically cached or enums

§Usage & Appendix

This API defaults to using reqwest and tokio for non-blocking IO, there is a ureq feature to switch to ureq and parking_lot for blocking IO.
Use PlayStream for obtaining live updates on games.
Use single_stat! for simple stat requests rather than making person_hydrations! and PersonRequest yourself.
Use as_complete_or_request and the numerous crate::*_hydrations! items to obtain additional information in requests, try to minimize request quantity.
The precache function allows caching commonly requested values before usage to make as_complete_or_request faster to use.
Supply SeasonIds to requests to not have them break when the year changes.

Modules§

all_star: Unimplemented as you can only get data as the ASG is ongoing.
attendance: Attendance for games and seasons.
awards: An award, such as the Cy Young, MVP, etc.
cache: The caching feature of mlb-api
conference: A conference, like in NCAA Baseball.
division: A division, like the AL East or NL West.
draft: Draft endpoint data. Picks, rounds, etc.
game: The thing you’re most likely here for.
home_run_derby: Needs to be a home run derby for me to implement this one
hydrations: General hydrations types for the hydrations system
jobs: Jobs data.
league: Leagues; AL, NL, etc.
meta: An abstraction over endpoints that contain fixed data, such as GameTypes, JobTypes, etc.
person: A description of a person in baseball.
request: Handles the request portion of the code; uses [::ureq] or ::reqwest for blocking or non-blocking networking.
schedule: Schedules, typically the main entrypoint to navigate through games.
season: Data about important dates in a season for a specific SportId.
sport: Different “sports”; MLB, AAA, AA, A+, A, Rookieball, etc.
standings: Standings of a team, wins, losses, etc
stats: The Stats API
team: Endpoints related to teams; roster, history, affiliates, etc.
transactions: Roster transactions; calling someone up, free agent signings, etc.
venue: Venues; Yankee Stadium, Rogers Centre, Dodger Stadium, etc.

Macros§

person_hydrations: Creates hydrations for a person
roster_hydrations: Creates hydrations for a RosterRequest.
schedule_hydrations: Creates hydrations for a schedule
single_stat: Shorthand function for getting a single [StatType] and [StatGroup] for a specific player.
sports_hydrations: Creates hydrations for a sport
standings_hydrations: Creates hydrations for a standings request
stats_hydrations: Generates stat data types to be used in requests.
team_hydrations: Creates hydrations for a team
venue_hydrations: Creates hydrations for a venue

Structs§

ExternalReference: More generalized than social media, includes retrosheet, fangraphs, (+ some socials), etc.
FieldInfo: Various information regarding a field.
HomeAway: General type that represents two fields where one is home and one is away
Location: Street address, city, etc.
MLBError: Represents an error parsing an HTTP request
RGBAColor: rgba({red}, {green}, {blue}) into a type
ResourceUsage
TimeZoneData: Data regarding a timezone, uses chrono_tz.
TrackingSystem: Tracking equipment, Hawk-Eye, PitchFx, etc.
TrackingSystemVendor: A vendor for specific tracking concepts, such as Hawk-Eye for skeletal data.
TrackingSystemVendorId

Enums§

Copyright: The copyright at the top of every request
DayHalf: AM/PM
Gender: Gender
Handedness: Handedness
HandednessParseError: Error for handedness parsing
HeatmapTemperature: Used in HittingHotColdZones and PitchingHotColdZones.
HeightMeasurement: Measurement of a person’s height
HeightMeasurementParseError: Error for [<HeightMeasurement as FromStr>::from_str]
IntegerOrFloatStat: Stat that is either an integer or float.
PlayerPool: General filter for players in requests
RGBAColorFromStrError: Spec: rgba({red}, {green}, {blue})
RoofType: Different types of roof setups.
TeamSide
TurfType: Different types of turf.

Functions§

deserialize_team_side_from_is_home
deserialize_time_delta_from_hms: Errors
from_str: Deserializes a type using its FromStr implementation.
from_yes_no: Deserializes a "Y" or "N" into a bool
try_from_str: Try to deserialize a type using its FromStr implementation, fallback to None if it doesn’t work.

Type Aliases§

NaiveDateRange: Represents a range from one date to another (inclusive on both ends)

Crate mlb_api

Crate mlb_api Copy item path

§The Rust MLB API Wrapper

§Usage

§Endpoints

§Usage & Appendix

Modules§

Macros§

Structs§

Enums§

Functions§

Type Aliases§

Crate mlb_api