> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odds-api.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Odds-API.io in 5 minutes. Sign up for free, get your API key, and make your first call to fetch real-time betting odds.

## Make your first API call

Get up and running with Odds-API.io and fetch your first odds data.

### Step 1: Get your API key

<Steps>
  <Step title="Sign up for free">
    Visit [odds-api.io](https://odds-api.io) and sign up for a free account.
  </Step>

  <Step title="Check your email">
    Your API key will be sent to the email address you provided during signup.
  </Step>

  <Step title="Copy your API key">
    Copy the API key from the email and keep it secure!
  </Step>
</Steps>

<Warning>
  Never share your API key publicly or commit it to version control. Use environment variables to store it securely.
</Warning>

### Step 2: Fetch available sports

Let's start by fetching the list of available sports.

<Note>
  The `/sports` endpoint doesn't require authentication - you can try it before getting your API key!
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.odds-api.io/v3/sports"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.odds-api.io/v3/sports');
  const sports = await response.json();
  console.log(sports);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('https://api.odds-api.io/v3/sports')
  sports = response.json()
  print(sports)
  ```

  ```php PHP theme={null}
  <?php
  $response = file_get_contents('https://api.odds-api.io/v3/sports');
  $sports = json_decode($response, true);
  print_r($sports);
  ```
</CodeGroup>

**Example Response:**

```json theme={null}
[
  {
    "name": "Football",
    "slug": "football"
  },
  {
    "name": "Basketball",
    "slug": "basketball"
  },
  {
    "name": "Tennis",
    "slug": "tennis"
  }
]
```

### Step 3: Fetch events for a sport

Now let's get upcoming football events:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.odds-api.io/v3/events?apiKey=YOUR_API_KEY&sport=football&limit=10"
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.ODDS_API_KEY;
  const response = await fetch(
    `https://api.odds-api.io/v3/events?apiKey=${apiKey}&sport=football&limit=10`
  );
  const events = await response.json();
  console.log(events);
  ```

  ```python Python theme={null}
  import requests
  import os

  api_key = os.environ['ODDS_API_KEY']
  response = requests.get(
      'https://api.odds-api.io/v3/events',
      params={
          'apiKey': api_key,
          'sport': 'football',
          'limit': 10
      }
  )
  events = response.json()
  print(events)
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = getenv('ODDS_API_KEY');
  $url = 'https://api.odds-api.io/v3/events?' . http_build_query([
      'apiKey' => $apiKey,
      'sport' => 'football',
      'limit' => 10
  ]);
  $response = file_get_contents($url);
  $events = json_decode($response, true);
  print_r($events);
  ```
</CodeGroup>

**Example Response:**

```json theme={null}
[
  {
    "id": 123456,
    "sport": {
      "name": "Football",
      "slug": "football"
    },
    "league": {
      "name": "Premier League",
      "slug": "england-premier-league"
    },
    "home": "Manchester United",
    "away": "Liverpool",
    "date": "2025-10-15T15:00:00Z",
    "status": "settled",
    "scores": {
      "home": 2,
      "away": 1,
      "periods": {
        "p1": { "home": 1, "away": 0 },
        "ft": { "home": 2, "away": 1 }
      }
    }
  }
]
```

<Note>
  The `scores` object includes the final result (`home`/`away`, OT/penalty-inclusive) along with a `periods` map. Period keys: `p1`…`pN` (periods/sets/quarters), `ft` (full time), `ot` (overtime/extra time), `ap` (penalty shootout), `currentgame` (live tennis), `map1`…`mapN` (esports). The full-time key is `ft` (the legacy feed used `fulltime`).
</Note>

### Step 4: Get odds for an event

Finally, let's fetch odds from multiple bookmakers for a specific event:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.odds-api.io/v3/odds?apiKey=YOUR_API_KEY&eventId=123456&bookmakers=Bet365,Unibet,SingBet"
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.ODDS_API_KEY;
  const eventId = 123456;
  const bookmakers = 'Bet365,Unibet,SingBet';

  const response = await fetch(
    `https://api.odds-api.io/v3/odds?apiKey=${apiKey}&eventId=${eventId}&bookmakers=${bookmakers}`
  );
  const odds = await response.json();
  console.log(odds);
  ```

  ```python Python theme={null}
  import requests
  import os

  api_key = os.environ['ODDS_API_KEY']
  event_id = 123456
  bookmakers = 'Bet365,Unibet,SingBet'

  response = requests.get(
      'https://api.odds-api.io/v3/odds',
      params={
          'apiKey': api_key,
          'eventId': event_id,
          'bookmakers': bookmakers
      }
  )
  odds = response.json()
  print(odds)
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = getenv('ODDS_API_KEY');
  $eventId = 123456;
  $bookmakers = 'Bet365,Unibet,SingBet';

  $url = 'https://api.odds-api.io/v3/odds?' . http_build_query([
      'apiKey' => $apiKey,
      'eventId' => $eventId,
      'bookmakers' => $bookmakers
  ]);
  $response = file_get_contents($url);
  $odds = json_decode($response, true);
  print_r($odds);
  ```
</CodeGroup>

**Example Response:**

```json theme={null}
{
  "id": 123456,
  "home": "Manchester United",
  "away": "Liverpool",
  "date": "2025-10-15T15:00:00Z",
  "status": "pending",
  "urls": {
    "Bet365": "https://www.bet365.com/...",
    "Unibet": "https://www.unibet.com/...",
    "SingBet": "https://www.unibet.com/..."
  },
  "bookmakers": {
    "Bet365": [
      {
        "name": "ML",
        "odds": [
          {
            "home": "2.10",
            "draw": "3.40",
            "away": "3.20"
          }
        ],
        "updatedAt": "2025-10-04T10:30:00Z"
      }
    ],
    "Unibet": [
      {
        "name": "ML",
        "odds": [
          {
            "home": "2.15",
            "draw": "3.35",
            "away": "3.15"
          }
        ],
        "updatedAt": "2025-10-04T10:29:45Z"
      }
    ],
    "SingBet": [
      {
        "name": "ML",
        "odds": [
          {
            "home": "2.00",
            "draw": "3.25",
            "away": "3.25"
          }
        ],
        "updatedAt": "2025-10-04T10:29:42Z"
      }
    ]
  }
}
```

## Common Use Cases

Here are quick snippets for common scenarios:

### Find Best Odds for a Match

```javascript theme={null}
// Compare odds across bookmakers
const bestOdds = {};
Object.entries(odds.bookmakers).forEach(([bookmaker, markets]) => {
  const ml = markets.find(m => m.name === 'ML')?.odds[0];
  if (ml) {
    if (!bestOdds.home || parseFloat(ml.home) > parseFloat(bestOdds.home.odds)) {
      bestOdds.home = { bookmaker, odds: ml.home };
    }
  }
});

console.log(`Best home odds: ${bestOdds.home.odds} at ${bestOdds.home.bookmaker}`);
```

### Filter Events by League

```javascript theme={null}
const apiKey = process.env.ODDS_API_KEY;

// Get Premier League matches only
const response = await fetch(
  `https://api.odds-api.io/v3/events?apiKey=${apiKey}&sport=football&league=england-premier-league`
);

const matches = await response.json();
console.log(`Found ${matches.length} Premier League matches`);
```

### Get Live Events

```javascript theme={null}
const apiKey = process.env.ODDS_API_KEY;

// Fetch events that are currently in play
const response = await fetch(
  `https://api.odds-api.io/v3/events?apiKey=${apiKey}&sport=football&status=live`
);

const liveMatches = await response.json();
console.log(`${liveMatches.length} matches currently live`);
```

## Error Handling

Always handle errors gracefully in production:

```javascript theme={null}
async function fetchOdds(eventId) {
  const apiKey = process.env.ODDS_API_KEY;

  try {
    const response = await fetch(
      `https://api.odds-api.io/v3/odds?apiKey=${apiKey}&eventId=${eventId}&bookmakers=Bet365`
    );

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error('Invalid API key');
      }
      if (response.status === 429) {
        throw new Error('Rate limit exceeded - please wait before retrying');
      }
      if (response.status === 404) {
        throw new Error(`Event ${eventId} not found`);
      }
      throw new Error(`API error: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to fetch odds:', error.message);
    throw error;
  }
}
```

## Next steps

Now that you've made your first API calls, explore these guides:

<CardGroup cols={2}>
  <Card title="SDKs & Libraries" icon="code" href="/guides/sdks">
    Official Python, Node.js, and MCP SDKs for faster integration.
  </Card>

  <Card title="Fetching Odds" icon="chart-line" href="/guides/fetching-odds">
    Deep dive into fetching and comparing odds from multiple bookmakers.
  </Card>

  <Card title="Value Bets" icon="magnifying-glass-dollar" href="/guides/value-bets">
    Learn how to identify profitable betting opportunities.
  </Card>

  <Card title="WebSocket Feed" icon="bolt" href="/guides/websockets">
    Real-time odds updates via WebSocket.
  </Card>
</CardGroup>

<Note>
  **Need help?** Contact us at [hello@odds-api.io](mailto:hello@odds-api.io) - we're here to help!
</Note>