Major League Baseball Person API

openapi: 3.2.0
info:
  title: Stats API Documentation Analytics Person API
  description: Official API for Major League Baseball.
  version: 2.0.0
servers:
- url: https://statsapi.mlb.com
  description: Production
- url: https://beta-statsapi.mlb.com
  description: Beta
- url: https://qa-statsapi.mlb.com
  description: QA
- url: http://localhost:8080
  description: Local
tags:
- name: Person
  description: Operations pertaining to players
paths:
  /api/v1/people/{personId}/stats:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: stats_3
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
        x-lookup:
          name: Stat Types
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Sports
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: opposingPlayerId
        in: query
        description: A unique identifier for the opposing team
        required: false
        schema:
          type: integer
          format: int32
      - name: metrics
        in: query
        description: Name of metric(s) for metric log stats.  Available metrics in /api/v1/metrics
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MetricType'
      - name: leagueId
        in: query
        description: Unique League Identifier
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Leagues
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
        x-lookup:
          name: League Lists
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: array
          items:
            type: string
        x-lookup:
          name: Situation Codes
      - name: combineSits
        in: query
        description: 'If true, gathers stats where all of the situational criteria are met. If false, returns stats where any of the situational criteria are met. Default: false'
        required: false
        schema:
          type: boolean
      - name: startDate
        in: query
        description: 'Start date for range of data (must be used with end date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'End date for range of data (must be used with start date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: daysBack
        in: query
        description: Returns results from the last 'X' days (Starting from yesterday).
        required: false
        schema:
          type: integer
          format: int32
      - name: gamesBack
        in: query
        description: Returns results from the last 'X' games played.
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: eventType
        in: query
        description: Type of event
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/EventType'
      - name: pitchType
        in: query
        description: Classification of pitch (fastball, curveball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: hitTrajectory
        in: query
        description: Trajectory of hit (line drive, fly ball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/HitTrajectory'
      - name: batSide
        in: query
        description: Bat side of hitter
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
        x-lookup:
          name: Game Types
      - name: groupBy
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GroupByEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/people/{personId}/stats/metrics:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: statsMetrics
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
        x-lookup:
          name: Stat Types
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Sports
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: opposingPlayerId
        in: query
        description: A unique identifier for the opposing team
        required: false
        schema:
          type: integer
          format: int32
      - name: metrics
        in: query
        description: Name of metric(s) for metric log stats.  Available metrics in /api/v1/metrics
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MetricType'
      - name: leagueId
        in: query
        description: Unique League Identifier
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Leagues
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
        x-lookup:
          name: League Lists
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: array
          items:
            type: string
        x-lookup:
          name: Situation Codes
      - name: combineSits
        in: query
        description: 'If true, gathers stats where all of the situational criteria are met. If false, returns stats where any of the situational criteria are met. Default: false'
        required: false
        schema:
          type: boolean
      - name: startDate
        in: query
        description: 'Start date for range of data (must be used with end date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'End date for range of data (must be used with start date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: daysBack
        in: query
        description: Returns results from the last 'X' days (Starting from yesterday).
        required: false
        schema:
          type: integer
          format: int32
      - name: gamesBack
        in: query
        description: Returns results from the last 'X' games played.
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: eventType
        in: query
        description: Type of event
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/EventType'
      - name: pitchType
        in: query
        description: Classification of pitch (fastball, curveball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: hitTrajectory
        in: query
        description: Trajectory of hit (line drive, fly ball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/HitTrajectory'
      - name: batSide
        in: query
        description: Bat side of hitter
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Comma delimited list of type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
        x-lookup:
          name: Game Types
      - name: groupBy
        in: query
        description: Group stats by PLAYER, TEAM, SEASON, VENUE, SPORT or STAT_GROUP
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GroupByEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/people/{personId}/stats/game/{gamePk}:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: currentGameStats
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: gamePk
        in: path
        description: Unique Primary Key Representing a Game
        required: true
        schema:
          type: integer
          format: int32
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/people/{personId}/stats/game/current:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: currentGameStats_1
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/people/{personId}/awards:
    get:
      tags:
      - Person
      summary: View a players awards
      operationId: award
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AwardsRestObject'
  /api/v1/people/{personId}:
    get:
      tags:
      - Person
      summary: View a person(s) biographical information
      description: This endpoint allows you to pull the information of players, coaches and umpires
      operationId: person
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: personIds
        in: query
        description: 'Comma delimited list of person ID. Format: 1234, 2345'
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: accent
        in: query
        description: Boolean value to specify wanting a person's name with accents or without
        required: false
        schema:
          type: boolean
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PeopleRestObject'
  /api/v1/people:
    get:
      tags:
      - Person
      summary: View a person(s) biographical information
      description: This endpoint allows you to pull the information of players, coaches and umpires
      operationId: person_1
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: personIds
        in: query
        description: 'Comma delimited list of person ID. Format: 1234, 2345'
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: accent
        in: query
        description: Boolean value to specify wanting a person's name with accents or without
        required: false
        schema:
          type: boolean
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PeopleRestObject'
  /api/v1/people/search:
    get:
      tags:
      - Person
      summary: Search for a player by name
      operationId: search
      parameters:
      - name: names
        in: query
        description: Name a player uses
        required: false
        schema:
          type: array
          items:
            type: string
      - name: personIds
        in: query
        description: 'Comma delimited list of person ID. Format: 1234, 2345'
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Sports
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Leagues
      - name: teamIds
        in: query
        description: Comma delimited list of Unique Team identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
        x-lookup:
          name: League Lists
      - name: active
        in: query
        description: Whether or not a player is active
        required: false
        schema:
          type: boolean
      - name: verified
        in: query
        description: Complete and confirmed all biographical data
        required: false
        schema:
          type: boolean
      - name: rookie
        in: query
        description: Whether or not a player is a rookie
        required: false
        schema:
          type: boolean
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PeopleRestObject'
  /api/v1/people/freeAgents:
    get:
      tags:
      - Person
      summary: Get free agents
      operationId: freeAgents
      parameters:
      - name: season
        in: query
        description: Season of play
        required: true
        schema:
          type: string
      - name: order
        in: query
        description: The order of sorting, ascending or descending
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/FreeAgentListRestObject'
  /api/v1/people/changes:
    get:
      tags:
      - Person
      summary: View a players change log
      operationId: currentGameStats_2
      parameters:
      - name: updatedSince
        in: query
        description: 'Format: YYYY-MM-DDTHH:MM:SSZ'
        required: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The pointer to start for a return set; used for pagination
        required: false
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PeopleRestObject'
components:
  schemas:
    TeamStatData:
      type: object
      properties:
        requestingUserRole:
          $ref: '#/components/schemas/Role'
        note:
          type: string
        summary:
          type: object
          additionalProperties:
            type: string
          writeOnly: true
        catchersInterference:
          type: integer
          format: int32
        average:
          type: string
        onBasePercentage:
          type: string
        onBasePlusSlugging:
          type: string
        stolenBases:
          type: integer
          format: int32
        caughtStealing:
          type: integer
          format: int32
        slugging:
          type: string
        outs:
          type: integer
          format: int32
        gidp:
          type: integer
          format: int32
        gitp:
          type: integer
          format: int32
        homeRuns:
          type: integer
          format: int32
        numberOfPitches:
          type: integer
          format: int32
        totalBases:
          type: integer
          format: int32
        gidpOpportunites:
          type: integer
          format: int32
        walks:
          type: integer
          format: int32
        hitByPitch:
          type: integer
          format: int32
        strikeouts:
          type: integer
          format: int32
        airOuts:
          type: integer
          format: int32
        goAo:
          type: string
        pitchesPerPlateAppearance:
          type: number
          format: double
        intentionalWalks:
          type: integer
          format: int32
        groundOuts:
          type: integer
          format: int32
        flyOuts:
          type: integer
          format: int32
        games:
          type: integer
          format: int32
        gamesStarted:
          type: integer
          format: int32
        doubles:
          type: integer
          format: int32
        hits:
          type: integer
          format: int32
        triples:
          type: integer
          format: int32
        singles:
          type: integer
          format: int32
        runs:
          type: integer
          format: int32
        atBats:
          type: integer
          format: int32
        pickoffs:
          type: integer
          format: int32
        stolenBasePercentage:
          type: string
        wildPitches:
          type: integer
          format: int32
        sacFlies:
          type: integer
          format: int32
        sacBunts:
          type: integer
          format: int32
        putouts:
          type: integer
          format: int32
        assists:
          type: integer
          format: int32
        chances:
          type: integer
          format: int32
        streak:
          type: integer
          format: int32
        battingOrder:
          type: string
        totalSwings:
          type: integer
          format: int32
        swingsAndMisses:
          type: integer
          format: int32
        ballsInPlay:
          type: integer
          format: int32
        popOuts:
          type: integer
          format: int32
        lineOuts:
          type: integer
          format: int32
        flyHits:
          type: integer
          format: int32
        popHits:
          type: integer
          format: int32
        lineHits:
          type: integer
          format: int32
        groundHits:
          type: integer
          format: int32
        winStreak:
          type: integer
          format: int32
        lossStreak:
          type: integer
          format: int32
        plateAppearances:
          type: integer
          format: int32
        stolenBasePercentageOrNull:
          type: string
        pitchesPerPlateAppearanceStr:
          type: string
    InningTeamInfoRestObject:
      type: object
      properties:
        copyright:
          type: string
        runs:
          type: integer
          format: int32
        hits:
          type: integer
          format: int32
        errors:
          type: integer
          format: int32
        leftOnBase:
          type: integer
          format: int32
    BaseballPitch:
      type: object
      properties:
        ballColor:
          type: string
        trailColor:
          type: string
        startSpeed:
          type: number
          format: double
        endSpeed:
          type: number
          format: double
        nastyFactor:
          type: number
          format: double
        strikeZoneTop:
          type: number
          format: double
        strikeZoneBottom:
          type: number
          format: double
        strikeZoneWidth:
          type: number
          format: double
        strikeZoneDepth:
          type: number
          format: double
        getaX:
          type: number
          format: double
        getaY:
          type: number
          format: double
        getaZ:
          type: number
          format: double
        pfxX:
          type: number
          format: double
        pfxZ:
          type: number
          format: double
        getpX:
          type: number
          format: double
        getpZ:
          type: number
          format: double
        getvX0:
          type: number
          format: double
        getvY0:
          type: number
          format: double
        getvZ0:
          type: number
          format: double
        x:
          type: number
          format: double
        y:
          type: number
          format: double
        z0:
          type: number
          format: double
        y0:
          type: number
          format: double
        x0:
          type: number
          format: double
        breakAngle:
          type: number
          format: double
        breakLength:
          type: number
          format: double
        breakX:
          type: number
          format: double
        breakY:
          type: number
          format: double
        breakZ:
          type: number
          format: double
        zone:
          type: integer
          format: int32
        spinRate:
          type: integer
          format: int32
        spinDirection:
          type: integer
          format: int32
        typeConfidence:
          type: number
          format: double
        plateTime:
          type: number
          format: double
        extension:
          type: number
          format: double
    WeatherRestObject:
      type: object
      properties:
        copyright:
          type: string
        condition:
          type: string
        temp:
          type: string
        wind:
          type: string
    FreeAgentListRestObject:
      type: object
      properties:
        copyright:
          type: string
        hydrations:
          type: array
          items:
            type: string
        season:
          type: string
        freeAgents:
          type: array
          items:
            $ref: '#/components/schemas/FreeAgentRestObject'
    BaseballTeamStandingsRecord:
      type: object
      properties:
        team:
          $ref: '#/components/schemas/BaseballTeam'
        wins:
          type: integer
          format: int32
        losses:
          type: integer
          format: int32
        ties:
          type: integer
          format: int32
        gamesBack:
          type: string
      

# --- truncated at 32 KB (252 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/major-league-baseball/refs/heads/main/openapi/major-league-baseball-person-api-openapi.yml