apibaseball

TypeScript SDK for the API Baseball REST API. Zero runtime dependencies — uses native fetch (Node 18+ and browsers).

Install

npm install apibaseball

Requires Node.js 18+ (or any environment with a global fetch).

Quick start

import { BaseballClient } from "apibaseball";

const client = new BaseballClient({
  apiKey: process.env.APIBASEBALL_KEY!,
});

const leagues = await client.getLeagues({ page: 1 });
const games = await client.getGames({
  from: "2026-07-01",
  to: "2026-07-07",
});

Authentication

Pass your API key when constructing the client. By default it is sent as the X-Api-Key header.

const client = new BaseballClient({
  apiKey: "your-api-key",
});

To send the key as a query parameter (api_key) instead:

const client = new BaseballClient({
  apiKey: "your-api-key",
  authIn: "query",
});

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string | — | Required. Your API key. | | baseUrl | string | https://api.api-baseball.com/api | API base URL. | | authIn | "header" | "query" | "header" | Where to send the API key (X-Api-Key or api_key). | | fetch | typeof fetch | global fetch | Custom fetch implementation (useful for tests or polyfills). | | timeoutMs | number | disabled | Request timeout in milliseconds. 0 or omit to disable. |

API methods

All methods return the unwrapped result (or a Paginated<T> for paginated endpoints).

| Method | Endpoint | | --- | --- | | getCountries() | GET /baseball/countries | | getLeagues({ itemsPerPage?, page? }) | GET /baseball/leagues | | getLeaguesByCountry(countryId) | GET /baseball/countries/{countryId}/leagues | | getTeamsByLeague(leagueId) | GET /baseball/leagues/{leagueId}/teams | | getPlayers({ teamId?, leagueId? }) | GET /baseball/players | | getGames({ from, to, leagueId?, teamId?, itemsPerPage?, page? }) | GET /baseball/games | | getLiveGames() | GET /baseball/live | | getTeamInjuries(teamId) | GET /baseball/teams/{team_id}/injuries | | getTeamStats(teamId) | GET /baseball/teams/{team_id}/stats | | getOdds({ from, to, gameId? }) | GET /baseball/odds | | getStandings(leagueId) | GET /baseball/leagues/{league_id}/standings |

Examples

// Countries & leagues
const countries = await client.getCountries();
const { result: leagues, pagination } = await client.getLeagues({
  page: 1,
  itemsPerPage: 50,
});
const usLeagues = await client.getLeaguesByCountry(countries[0].id);

// Teams & players
const teams = await client.getTeamsByLeague(usLeagues[0].id);
const players = await client.getPlayers({ teamId: teams[0].id });

// Games (from/to required; max 6 months range)
const { result: games } = await client.getGames({
  from: "2026-07-01",
  to: "2026-07-07",
  leagueId: usLeagues[0].id,
});

// Live games
const live = await client.getLiveGames();

// Team injuries & stats
const injuries = await client.getTeamInjuries(teams[0].id);
const stats = await client.getTeamStats(teams[0].id);

// Odds (from/to required; max 5 days range)
const odds = await client.getOdds({
  from: "2026-07-01",
  to: "2026-07-05",
});

// Standings
const standings = await client.getStandings(usLeagues[0].id);

Pagination

Paginated methods (getLeagues, getGames) return:

type Paginated<T> = {
  result: T;
  pagination: {
    current_page: number;
    per_page: number;
    total: number;
    last_page: number;
    from: number | null;
    to: number | null;
  };
};

For getLeagues, the API currently ignores itemsPerPage (including "*") and always returns 15 leagues per page. To fetch every league, iterate page up to pagination.last_page:

const leagues = [];
for (let page = 1; ; page++) {
  const { result, pagination } = await client.getLeagues({ page });
  leagues.push(...result);
  if (page >= pagination.last_page) break;
}

getOdds accepts a date range of at most 5 days; longer ranges are rejected by the API with a BaseballApiError.

Error handling

Failed requests throw BaseballApiError when:

• HTTP status is >= 400
• The response envelope has success !== 1
• The request times out (if timeoutMs is set)
• The body is not valid JSON

import { BaseballClient, BaseballApiError } from "apibaseball";

try {
  await client.getGames({ from: "2026-07-01", to: "2026-07-07" });
} catch (err) {
  if (err instanceof BaseballApiError) {
    console.error(err.message, err.status, err.code);
  }
  throw err;
}

| Property | Description | | --- | --- | | status | HTTP status (0 if the request never completed, e.g. timeout). | | code | Optional API error code from the response body. | | body | Raw response body when available. |

Example

examples/dashboard is a runnable Express + browser dashboard that exercises every SDK method — see its README for setup.

Development

npm install
npm run build      # ESM + CJS + .d.ts via tsup
npm run typecheck  # tsc --noEmit
npm test           # vitest

License

MIT