openapi: 3.0.1
info:
  title: Stats API Documentation Analytics Bat Tracking 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: Bat Tracking
  description: 'Operations pertaining to bat tracking data '
paths:
  /api/v1/batTracking/game/{gamePk}/{playId}:
    get:
      tags:
      - Bat Tracking
      summary: View Bat Tracking Data by playId and gameId
      description: This endpoint allows you to pull bat tracking data by gameId and playId
      operationId: batTracking
      parameters:
      - name: gamePk
        in: path
        description: Unique Primary Key Representing a Game
        required: true
        schema:
          type: integer
          format: int32
      - name: playId
        in: path
        description: Unique play identifier
        required: true
        schema:
          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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatTrackingRestObject'
components:
  schemas:
    BatSweetSpotRestObject:
      type: object
      properties:
        copyright:
          type: string
        axialOffset:
          type: number
          description: Distance from the sweetSpot to the impact point along the bat. Negative is towards the handle of the bat, positive towards the head.
          format: double
        distanceFromHead:
          type: number
          description: Distance along the bat from the sweetSpot towards the head. Will be constant for all swings.
          format: double
        speedBeforeImpact:
          type: number
          description: The speed of the sweetSpot right before contact.
          format: double
        radialOffset:
          type: number
          description: Distance from the sweetSpot to the impact point perpendicular to the bat. Negative is below the center of the bat, positive is above.
          format: double
    BatImpactRestObject:
      type: object
      properties:
        copyright:
          type: string
        attackAngle:
          type: number
          description: The angle of the bat's path, at impact, relative to horizontal. A negative value represents swinging downward, a positive value upward.
          format: double
        speed:
          $ref: '#/components/schemas/BatImpactSpeedRestObject'
        contactPoint:
          $ref: '#/components/schemas/ContactPointPositionRestObject'
        headPosition:
          $ref: '#/components/schemas/HeadPositionRestObject'
        handlePosition:
          $ref: '#/components/schemas/HandlePositionRestObject'
        timeStamp:
          type: string
          description: TimeStamp when bat and ball either intersect in case of contact, or in cases where they don’t collide, timeStamp where ball is closest to any point along the bat.
    BatImpactSpeedRestObject:
      type: object
      properties:
        copyright:
          type: string
        before:
          type: number
          description: Speed of impact point right before contact.
          format: double
        after:
          type: number
          description: Speed of impact point right after contact.
          format: double
    PositionRestObject:
      type: object
      properties:
        copyright:
          type: string
        code:
          type: string
        name:
          type: string
        type:
          type: string
        abbreviation:
          type: string
    HandlePositionRestObject:
      type: object
      properties:
        copyright:
          type: string
        x:
          type: number
          description: Location in the horizontal dimension, negative toward third base, positive toward first base.
          format: double
        y:
          type: number
          description: Location in the depth dimension, negative toward the backstop, positive toward pitcher’s mound.
          format: double
        z:
          type: number
          description: Location in the vertical dimension, from the ground upward.
          format: double
        timeStamp:
          type: string
      description: Location of the handle of the bat during impact. The distance from head to handle is currently fixed at 32.677 inches.
    BatTrackingRestObject:
      type: object
      properties:
        copyright:
          type: string
        units:
          $ref: '#/components/schemas/JsonNode'
        gamePk:
          type: integer
          description: Unique game identifier.
          format: int32
        playId:
          type: string
          description: Unique play identifier (per game).
        impact:
          $ref: '#/components/schemas/BatImpactRestObject'
        sweetSpot:
          $ref: '#/components/schemas/BatSweetSpotRestObject'
        batPositions:
          type: array
          items:
            $ref: '#/components/schemas/BatPositionRestObject'
    BatPositionRestObject:
      type: object
      properties:
        copyright:
          type: string
        positionId:
          type: string
          description: Identifier for which part of the bat the positions/timeStamp represent. For now this will only be the “head” and the “handle”, but is subject to change in the future.
        positions:
          type: array
          description: Locations of the head of the bat at the given timeStamps.
          items:
            $ref: '#/components/schemas/PositionRestObject'
    JsonNode:
      type: object
    HeadPositionRestObject:
      type: object
      properties:
        copyright:
          type: string
        x:
          type: number
          description: Location in the horizontal dimension, negative toward third base, positive toward first base.
          format: double
        y:
          type: number
          description: Location in the depth dimension, negative toward the backstop, positive toward pitcher’s mound.
          format: double
        z:
          type: number
          description: Location in the vertical dimension, from the ground upward.
          format: double
        timeStamp:
          type: string
      description: Location of the head of the bat during impact.
    ContactPointPositionRestObject:
      type: object
      properties:
        copyright:
          type: string
        x:
          type: number
          description: Location in the horizontal dimension, negative toward third base, positive toward first base.
          format: double
        y:
          type: number
          description: Location in the depth dimension, negative toward the backstop, positive toward pitcher’s mound.
          format: double
        z:
          type: number
          description: Location in the vertical dimension, from the ground upward.
          format: double
        timeStamp:
          type: string
      description: Location of impact point.