Baseball API Client

The Baseball API Client is a small Python toolkit and CLI for fetching MLB data from the Sportsradar MLB API. It provides:

• A simple CLI for interactive and scripted requests.
• Programmatic helpers that return pandas DataFrames for easy analysis and export.
• JSON -> tabular flatteners for common nested responses (teams, standings, awards).

API Reqirements

A Sportsradar MLB API key is required. Official API information is available at: https://marketplace.sportradar.com/products/64076f13822569c8fbf1fd7c

Runtime Requirements

• pandas>=1.3
• requests>=2.25
• vcrpy>=4.1
• python-dateutil>=2.8

Install from requirements.txt:

pip install -r requirements.txt

Configuration

The program uses a default config file called mlb_config.json. An example config file called sample_config.json is provided. A valid config file that follows the sample_config.json is required.

To create/update your own config file, take the following steps:

1. Fill out your API_KEY, ACCESS_LEVEL and LANGUAGE in the CREDENTIALS section.
2. Ensure that the endpoints and match provided enpoints in sample_config.json.
3. Ensure that the json structure matches sample_config.json.
4. Ensure that the config file is saved in the project's root directory.
5. (Optional) Change the default config argument in utils/io/load_config from mlb_config.json to your config filename.

Usage

• Interactive:

python baseball_api_client.py

• Available command-line arguments:

• -c, --config (str)

  • Path to the config JSON. Default: config/mlb_config.json.
  • Example: -c config/custom_config.json

• -d, --date (str)

  • Date for daily endpoints in YYYY-MM-DD format (zero-padded or not).
  • Example: -d 2024-07-05

• -dt, --data_type, --datatype (str)

  • Which endpoint to call (e.g., schedule, standings, injuries, transactions).
  • Must match one of the keys from ENDPOINTS in your config (case-insensitive).
  • Example: -dt schedule

• -s, --seasonal (str)

  • Season year for seasonal endpoints (e.g., 2024).
  • Used together with -st or when requesting seasonal data types.
  • Example: -s 2024

• -st, --season_type, --season-type (REG|PRE)

  • Season type, uppercased automatically. Allowed values: REG (regular), PRE (preseason).
  • Defaults to REG when omitted.
  • Example: -st PRE

Testing

To avoid over-querying the API when running the integration tests, use VCR to record the test once, then run the test in replay-mode.

• To record a test use the following commands:
  • Windows CMD:

    set RECORD_VCR=1
    python -m unittest tests.integration.test_vcr_endpoints.TestVcrRequestsMulti -v
    set RECORD_VCR=

  • PowerShell:

    $env:RECORD_VCR = "1"
    python -m unittest tests.integration.test_vcr_endpoints.TestVcrRequestsMulti -v
    Remove-Item Env:RECORD_VCR

• To run the tests in replay-mode, do NOT set RECORD_VCR=1.

Directory layout

• config/ — configs (do NOT commit config files with real API keys.)
• utils/ — core helpers, endpoints, io
• tests/ — unit tests
• tests/cassettes/ — VCR cassettes (do NOT commit any files in cassettes as they contain your API key.)
• output/ — CSV outputs generated by CLI

Security

The config files and any VCR cassettes that been recorded for integration testing CONTAIN your API key. Do NOT share or commit any of these files.

Ackknowledgements

The code in this project is open-source and was created as a side learning project to explore API requests. It was not and should not be used for commercial applications. I am not associated with Sportsradar in any fashion. The API is 100% owned/updated/maintained by Sportsradar. Big thanks to Sportsradar for making the MLB API available for baseball/coding enthusiasts. If you like the API, check out https://marketplace.sportradar.com/ to view/trial/purchase access to any of their wonderful sports APIs.