@betalytics/api/README.md

TypeScript SDK for Betalytics API - Sports analytics and betting data

# Betalytics API

A TypeScript SDK for accessing the Betalytics API.

See additional endpoint documentation here: https://www.betalytics.com/api/docs

## Installation

```bash
# npm
npm install @betalytics/api
# bun
bun add @betalytics/api
```

## Quick Start

```typescript
import { BetalyticsClient } from '@betalytics/api';

const API_KEY = process.env.BA_API_KEY
const betalyticsApi = new BetalyticsClient({
  headers: {
    "X-API-Key": API_KEY,
  },
  baseURL: 'https://api.betalytics.com'
});

const nbaPlayerProps = await betalyticsApi.nba.player.getBets({
  query: {
    player: 'Shai Gilgeous-Alexander',
    market: "player_points",
  }
});
```

## NFL Player Fantasy


```typescript
import { BetalyticsClient } from '@betalytics/api';

const API_KEY = process.env.BA_API_KEY
const betalyticsApi = new BetalyticsClient({
  headers: {
    "X-API-Key": API_KEY,
  },
  baseURL: 'https://api.betalytics.com'
});

const nflPlayerFantasyOptions = await betalyticsApi.nfl.player.getFantasyOptions()
const options = nflPlayerFantasyOptions.data?.results
const teams = options?.fields_filter_options.player_team
const positions = options?.fields_filter_options.player_position

const selectedTeam = teams?.[2] || "BAL"
const selectedPosition = positions?.[2] || "RB"

const nflPlayerFantasy = await betalyticsApi.nfl.player.getFantasy({
  query: {
    player_team: selectedTeam,
    player_position: selectedPosition,
  },
})
console.log(nflPlayerFantasy.data)
```


## Features

- **TypeScript Support**: Full TypeScript support with auto-generated types
- **Multiple Sports**: Support for NBA, NFL, MLB, NHL, Soccer, and NCAAF
- **Organized API**: Clean, organized API by sport and data type
- **Flexible Usage**: Use individual sport clients, main client class, or raw functions
- **Modern API**: Built with the latest OpenAPI specifications and @hey-api/openapi-ts
- **Tree-shakeable**: Import only what you need
- **Type-safe**: All requests and responses are fully typed

## API Coverage

### Sports Supported
- 🏀 **NBA** (National Basketball Association)
- 🏈 **NFL** (National Football League)
- ⚾ **MLB** (Major League Baseball)
- 🏒 **NHL** (National Hockey League)
- ⚽ **Soccer** (International leagues)
- 🏈 **NCAAF** (College Football)

### Data Types
- Game betting recommendations and odds
- Player prop betting data
- Player and team trends/statistics
- Shot heatmap data with coordinates (NHL)
- Interactive chart data for visualizations
- Goalscorer and goalie props (NHL)
- Historical betting data with timestamp filtering
- Partner integrations (BetOpenly)

## Usage Examples

### NBA Data

```typescript
import { BetalyticsClient } from '@betalytics/api';

const betalyticsApi = new BetalyticsClient();

// Get NBA game betting data
const nbaGames = await betalyticsApi.nba.games.getBets({
  query: {
    limit: 20,
    game_date_from: '2024-01-01',
    sort: ['home_ml_grade'],
    order: ['desc']
  }
});

// Get NBA player props
const playerProps = await betalyticsApi.nba.player.getBets({
  query: {
    player: 'LeBron James',
    market: ['points', 'rebounds', 'assists'],
    bet_grade_from: 2,
    limit: 10
  }
});

// Get NBA player trends
const playerTrends = await betalyticsApi.nba.player.getTrends({
  query: {
    player_name: 'Stephen Curry',
    period: ['season', 'last_10_games'],
    stat_name: ['points', 'threes']
  }
});
```

### NHL Data

```typescript
import { BetalyticsClient } from '@betalytics/api';

const betalyticsApi = new BetalyticsClient();

// Get NHL game betting data
const nhlGames = await betalyticsApi.nhl.games.getBets({
  query: {
    game_date: '2024-01-15',
    league: ['NHL'],
    sort: ['over_grade'],
    order: ['desc']
  }
});

// Get NHL player shot heatmap data
const playerShots = await betalyticsApi.nhl.player.getShots({
  query: {
    player_name: 'Connor McDavid',
    period: 'season',
    player_team: 'Edmonton Oilers'
  }
});

// Get NHL goalscorer props
const goalscorerProps = await betalyticsApi.nhl.goalscorer.getBets({
  query: {
    game_date: '2024-01-15',
    bet_grade_from: 3,
    sort: ['bet_grade'],
    order: ['desc']
  }
});
```

### MLB Data

```typescript
import { BetalyticsClient } from '@betalytics/api';

const betalyticsApi = new BetalyticsClient();

// Get MLB game betting data
const mlbGames = await betalyticsApi.mlb.games.getBets({
  query: {
    game_date_from: '2024-04-01',
    game_date_to: '2024-04-07',
    over_grade_from: 8.0,
    sort: ['game_time'],
    order: ['asc']
  }
});

// Get MLB player props
const batterProps = await betalyticsApi.mlb.player.getBets({
  query: {
    player: 'Aaron Judge',
    market: ['home_runs', 'hits', 'rbis'],
    game_date: '2024-04-15'
  }
});

// Get MLB team trends
const teamTrends = await betalyticsApi.mlb.team.getTrends({
  query: {
    team_name: 'New York Yankees',
    period: ['season', 'last_10_games'],
    stat_name: ['runs_scored', 'runs_allowed']
  }
});
```

### NFL Data

```typescript
import { BetalyticsClient } from '@betalytics/api';

const betalyticsApi = new BetalyticsClient();

// Get NFL game betting data
const nflGames = await betalyticsApi.nfl.games.getBets({
  query: {
    game_date: '2024-01-14',
    home_ml_grade_from: 8.0,
    sort: ['game_time'],
    order: ['asc']
  }
});

// Get NFL player props
const playerProps = await betalyticsApi.nfl.player.getBets({
  query: {
    player: 'Patrick Mahomes',
    market: ['passing_yards', 'passing_touchdowns'],
    game_date: '2024-01-14'
  }
});

// Get NFL touchdown props
const touchdownProps = await betalyticsApi.nfl.touchdown.getBets({
  query: {
    game_date: '2024-01-14',
    player_position: ['RB', 'WR', 'TE'],
    bet_grade_from: 2
  }
});
```

### Soccer Data

```typescript
import { BetalyticsClient } from '@betalytics/api';

const betalyticsApi = new BetalyticsClient();

// Get soccer game betting data
const soccerGames = await betalyticsApi.soccer.games.getBets({
  query: {
    league: ['Premier League', 'La Liga'],
    game_date_from: '2024-01-01',
    home_ml_grade_from: 8.0,
    sort: ['game_time'],
    order: ['asc']
  }
});

// Get available filter options
const filterOptions = await betalyticsApi.soccer.games.getBetsOptions();
console.log(filterOptions.data.results.fields_filter_options);
```

## Query Parameters

Most endpoints support common query parameters:

- **Pagination**: `offset`, `limit`
- **Filtering**: `game_date_from`, `game_date_to`, `bookmaker`, `league`, `player`, `team`
- **Historical Filtering**: `historical_date_from`, `historical_date_to`
- **Sorting**: `sort`, `order`
- **Grading**: `bet_grade_from`, `bet_grade_to`, `home_ml_grade_from`, etc.
- **Display**: `mode` ('expand' or 'compact')

## Response Types

All responses are fully typed. Common response structure:

```typescript
{
  data: {
    count: number;           // Items in current page
    total_count: number;     // Total items available
    results: Array<T>;       // Array of typed results
  }
}
```

## Error Handling

```typescript
import { BetalyticsClient } from '@betalytics/api';

const betalyticsApi = new BetalyticsClient();

try {
  const response = await betalyticsApi.nba.games.getBets({
    query: { limit: 10 }
  });
  
  if (response.error) {
    console.error('API Error:', response.error);
  } else {
    console.log('Success:', response.data);
  }
} catch (error) {
  console.error('Network Error:', error);
}
```

## Available APIs

### NBA
- `betalyticsApi.nba.games.getBets()` - NBA game betting data
- `betalyticsApi.nba.games.getBetsOptions()` - NBA game betting options
- `betalyticsApi.nba.player.getBets()` - NBA player props
- `betalyticsApi.nba.player.getBetsOptions()` - NBA player prop options
- `betalyticsApi.nba.player.getTrends()` - NBA player trends
- `betalyticsApi.nba.player.getTrendsOptions()` - NBA player trend options
- `betalyticsApi.nba.team.getTrends()` - NBA team trends
- `betalyticsApi.nba.team.getTrendsOptions()` - NBA team trend options
- `betalyticsApi.nba.historical.games.getBets()` - NBA historical game betting data
- `betalyticsApi.nba.historical.games.getBetsOptions()` - NBA historical game betting options
- `betalyticsApi.nba.historical.player.getBets()` - NBA historical player props
- `betalyticsApi.nba.historical.player.getBetsOptions()` - NBA historical player prop options

### NFL
- `betalyticsApi.nfl.games.getBets()` - NFL game betting data
- `betalyticsApi.nfl.games.getBetsOptions()` - NFL game betting options
- `betalyticsApi.nfl.player.getBets()` - NFL player props
- `betalyticsApi.nfl.player.getBetsOptions()` - NFL player prop options
- `betalyticsApi.nfl.player.getTrends()` - NFL player trends
- `betalyticsApi.nfl.player.getTrendsOptions()` - NFL player trend options
- `betalyticsApi.nfl.player.getFantasy()` - NFL player fantasy data
- `betalyticsApi.nfl.player.getFantasyOptions()` - NFL player fantasy options
- `betalyticsApi.nfl.team.getTrends()` - NFL team trends
- `betalyticsApi.nfl.team.getTrendsOptions()` - NFL team trend options
- `betalyticsApi.nfl.touchdown.getBets()` - NFL touchdown props
- `betalyticsApi.nfl.touchdown.getBetsOptions()` - NFL touchdown prop options
- `betalyticsApi.nfl.historical.games.getBets()` - NFL historical game betting data
- `betalyticsApi.nfl.historical.games.getBetsOptions()` - NFL historical game betting options
- `betalyticsApi.nfl.historical.player.getBets()` - NFL historical player props
- `betalyticsApi.nfl.historical.player.getBetsOptions()` - NFL historical player prop options

### MLB
- `betalyticsApi.mlb.games.getBets()` - MLB game betting data
- `betalyticsApi.mlb.games.getBetsOptions()` - MLB game betting options
- `betalyticsApi.mlb.player.getBets()` - MLB player props
- `betalyticsApi.mlb.player.getBetsOptions()` - MLB player prop options
- `betalyticsApi.mlb.player.getTrends()` - MLB player trends
- `betalyticsApi.mlb.player.getTrendsOptions()` - MLB player trend options
- `betalyticsApi.mlb.team.getTrends()` - MLB team trends
- `betalyticsApi.mlb.team.getTrendsOptions()` - MLB team trend options
- `betalyticsApi.mlb.historical.games.getBets()` - MLB historical game betting data
- `betalyticsApi.mlb.historical.games.getBetsOptions()` - MLB historical game betting options
- `betalyticsApi.mlb.historical.player.getBets()` - MLB historical player props
- `betalyticsApi.mlb.historical.player.getBetsOptions()` - MLB historical player prop options

### NHL
- `betalyticsApi.nhl.games.getBets()` - NHL game betting data
- `betalyticsApi.nhl.games.getBetsOptions()` - NHL game betting options
- `betalyticsApi.nhl.player.getBets()` - NHL player props
- `betalyticsApi.nhl.player.getBetsOptions()` - NHL player prop options
- `betalyticsApi.nhl.player.getTrends()` - NHL player trends
- `betalyticsApi.nhl.player.getTrendsOptions()` - NHL player trend options
- `betalyticsApi.nhl.player.getShots()` - NHL player shot heatmaps
- `betalyticsApi.nhl.player.getShotsOptions()` - NHL player shot options
- `betalyticsApi.nhl.team.getTrends()` - NHL team trends
- `betalyticsApi.nhl.team.getTrendsOptions()` - NHL team trend options
- `betalyticsApi.nhl.team.getShots()` - NHL team shot heatmaps
- `betalyticsApi.nhl.team.getShotsOptions()` - NHL team shot options
- `betalyticsApi.nhl.goalscorer.getBets()` - NHL goalscorer props
- `betalyticsApi.nhl.goalscorer.getBetsOptions()` - NHL goalscorer prop options
- `betalyticsApi.nhl.goalie.getBets()` - NHL goalie props
- `betalyticsApi.nhl.goalie.getBetsOptions()` - NHL goalie prop options
- `betalyticsApi.nhl.historical.games.getBets()` - NHL historical game betting data
- `betalyticsApi.nhl.historical.games.getBetsOptions()` - NHL historical game betting options
- `betalyticsApi.nhl.historical.player.getBets()` - NHL historical player props
- `betalyticsApi.nhl.historical.player.getBetsOptions()` - NHL historical player prop options

### Soccer
- `betalyticsApi.soccer.games.getBets()` - Soccer game betting data
- `betalyticsApi.soccer.games.getBetsOptions()` - Soccer game betting options
- `betalyticsApi.soccer.historical.games.getBets()` - Soccer historical game betting data
- `betalyticsApi.soccer.historical.games.getBetsOptions()` - Soccer historical game betting options

### NCAAF
- `betalyticsApi.ncaaf.games.getBets()` - NCAAF game betting data
- `betalyticsApi.ncaaf.games.getBetsOptions()` - NCAAF game betting options
- `betalyticsApi.ncaaf.historical.games.getBets()` - NCAAF historical game betting data
- `betalyticsApi.ncaaf.historical.games.getBetsOptions()` - NCAAF historical game betting options

### Partners
- `betalyticsApi.partners.betOpenly.getStatus()` - BetOpenly API status
- `betalyticsApi.partners.betOpenly.getOpenBets()` - BetOpenly open bets