OddsFeed API

Appearance

HugeAPI - OddsFeed API Tutorial ​

Table of Contents ​

Introduction ​

The OddsFeed API provides comprehensive access to sports betting odds, including live and pre-match odds, historical data, scores, and results. It covers multiple sports and integrates with several major bookmakers.

Key Features ​

  • Historical odds: Access historical odds, scores, and results with charts showing odds movement, market openings, and closures
  • Live and Pre-Match odds: Football, Tennis, Basketball, Hockey, Baseball, Volleyball, Esports, MMA
  • Multiple Bookmakers: Coverage from major bookmakers including Pinnacle, Bet365, 1Xbet, Unibet, Stake.com, BetInAsia, and more
  • Real-time updates: Live betting odds and scores
  • Comprehensive data: Sports, categories, tournaments, seasons, events, and markets

External Resources ​

Connect and get an API key ​

Getting Started ​

Base URL ​

https://odds-feed-api.hgapi.top

Quick Start Example ​

Here's a simple example to get started:

bash
# Get list of all sports
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/sports" \
  -H "x-portal-apikey: YOUR_API_KEY"

Authentication ​

The API uses API key authentication. You need to include your API key in one of two ways:

http
x-portal-apikey: YOUR_API_KEY

Query Parameter Authentication ​

?x-portal-apikey=YOUR_API_KEY

Example with header authentication:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/sports" \
  -H "x-portal-apikey: your_api_key_here"

Example with query parameter:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/sports?x-portal-apikey=your_api_key_here"

Core Concepts ​

Data Hierarchy ​

The API data is organized in a hierarchical structure:

  1. Sports (e.g., Football, Tennis, Basketball)
  2. Categories (e.g., Brazil, USA, England)
  3. Tournaments (e.g., Premier League, NBA, Wimbledon)
  4. Seasons (e.g., 2023-2024, 2024)
  5. Events (e.g., Manchester United vs Arsenal)
  6. Markets (e.g., 1X2, Over/Under, Asian Handicap)
  7. Market Books (odds from specific bookmakers)

Market Types ​

  • 1X2: Traditional win/draw/lose betting
  • OVER_UNDER: Over/Under goals or points
  • ASIAN_HANDICAP: Asian handicap betting
  • HOME_AWAY: Home or Away betting
  • BOTH_TEAMS_TO_SCORE: Both teams to score betting

Market Placing ​

  • LIVE: Live/In-play markets
  • PREMATCH: Pre-match markets

Bet Types ​

  • BACK: Back betting (betting for something to happen)
  • LAY: Lay betting (betting against something to happen)

Event Status ​

  • FINISHED: Event has completed
  • LIVE: Event is currently in progress
  • SCHEDULED: Event is scheduled to start
  • CANCELLED: Event has been cancelled
  • DELAYED: Event has been delayed
  • INTERRUPTED: Event has been interrupted
  • POSTPONED: Event has been postponed
  • ABANDONED: Event has been abandoned

Bookmakers ​

The API supports odds from multiple bookmakers:

  • BETFAIR_EXCH: Betfair Exchange
  • MATCHBOOK: Matchbook
  • PINNACLE: Pinnacle
  • BET365: Bet365
  • 1XBET: 1XBet
  • ASIAN_ODDS: Asian Odds
  • BETFAIR: Betfair
  • UNIBET: Unibet
  • DAFABET: Dafabet
  • 888_SPORT: 888 Sport
  • WILLIAM_HILL: William Hill
  • BET_AT_HOME: Bet at Home
  • BWIN_ES: Bwin Spain
  • BET_IN_ASIA: Bet in Asia
  • STAKE_COM: Stake.com
  • BWIN: Bwin

API Endpoints ​

1. Sports List ​

Get a list of all available sports.

Endpoint: GET /api/v1/sports

Response Structure:

json
[
  {
    "id": 1,
    "name": "Football",
    "slug": "football"
  }
]

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/sports" \
  -H "x-portal-apikey: YOUR_API_KEY"

2. Categories List ​

Get a list of all categories (countries/regions).

Endpoint: GET /api/v1/categories

Response Structure:

json
[
  {
    "id": 1,
    "name": "Brazil",
    "slug": "brazil",
    "code": "br"
  }
]

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/categories" \
  -H "x-portal-apikey: YOUR_API_KEY"

3. Seasons List ​

Get a list of seasons with optional filtering.

Endpoint: GET /api/v1/seasons

Query Parameters:

  • page (integer): Page number (default: 0)
  • sport_id (integer, 1-15): Filter by sport ID
  • tournament_id (integer): Filter by tournament ID
  • year_start (integer): Filter by start year (e.g., 2024)

Response Structure:

json
{
  "total": 100,
  "per_page": 20,
  "current_page": 0,
  "last_page": 5,
  "data": [
    {
      "id": 1,
      "slug": "2023-2024",
      "year_start": 2023,
      "year_end": 2024,
      "sport": {
        "id": 1,
        "name": "Football",
        "slug": "football"
      },
      "tournament": {
        "id": 1,
        "name": "Premier League",
        "slug": "premier-league"
      }
    }
  ]
}

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/seasons?sport_id=1&year_start=2024&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

4. Tournaments List ​

Get a list of tournaments with optional filtering.

Endpoint: GET /api/v1/tournaments

Query Parameters:

  • page (integer): Page number (default: 0)
  • sport_id (integer, 1-15): Filter by sport ID
  • category_id (integer): Filter by category ID
  • tournament_ids (string): Comma-separated tournament IDs (e.g., "1,56,5,32")
  • name (string, min 3 chars, max 255): Filter by name

Response Structure:

json
{
  "total": 150,
  "per_page": 20,
  "current_page": 0,
  "last_page": 8,
  "data": [
    {
      "id": 1,
      "name": "Premier League",
      "slug": "premier-league",
      "category": {
        "id": 1,
        "name": "England",
        "slug": "england"
      },
      "sport": {
        "id": 1,
        "name": "Football",
        "slug": "football"
      }
    }
  ]
}

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/tournaments?sport_id=1&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

5. Events List ​

Get a list of events with extensive filtering options.

Endpoint: GET /api/v1/events

Query Parameters:

  • status (EventStatus): Filter by event status
  • event_ids (string): Comma-separated event IDs (max 100 items)
  • page (integer): Page number (default: 0)
  • sport_id (integer, 1-15): Filter by sport ID
  • category_id (integer): Filter by category ID
  • tournament_id (integer): Filter by tournament ID
  • season_id (integer): Filter by season ID
  • team_home (integer): Filter by home team ID
  • team_away (integer): Filter by away team ID
  • start_at_min (date-time): Minimum start date (UTC, format: "2024-07-10 20:00:00")
  • start_at_max (date-time): Maximum start date (UTC, format: "2024-07-15 20:00:00")

Response Structure:

json
{
  "total": 500,
  "per_page": 20,
  "current_page": 0,
  "last_page": 25,
  "data": [
    {
      "id": 709,
      "sport": {
        "id": 1,
        "name": "Football",
        "slug": "football"
      },
      "category": {
        "id": 1,
        "name": "Brazil",
        "slug": "brazil"
      },
      "tournament": {
        "id": 1,
        "name": "Serie A",
        "slug": "serie-a"
      },
      "season": {
        "id": 1,
        "slug": "2024",
        "year_start": 2024
      },
      "team_home": {
        "id": 1,
        "name": "Sao Paulo",
        "slug": "sao-paulo",
        "team_type": "TEAM"
      },
      "team_away": {
        "id": 2,
        "name": "Palmeiras",
        "slug": "palmeiras",
        "team_type": "TEAM"
      },
      "status": "FINISHED",
      "status_details": "FINISHED",
      "start_at": "2024-06-25 22:00:00.000",
      "winner": "HOME_WIN",
      "score_home": 2,
      "score_away": 1,
      "score_details": "Started: Live",
      "comments": "2024-06-25 22:00:00.000",
      "final_result_only": false,
      "main_outcome_0": 2.2,
      "main_outcome_1": 3.8,
      "main_outcome_2": 2.1,
      "main_volume_1": 2495,
      "main_volume_2": 5495
    }
  ]
}

Example Requests:

bash
# Get live football events
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?status=LIVE&sport_id=1&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

# Get specific events
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?event_ids=845,123,435,22,842,844,845" \
  -H "x-portal-apikey: YOUR_API_KEY"

# Get events in a date range
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?start_at_min=2024-07-10%2020:00:00&start_at_max=2024-07-15%2020:00:00" \
  -H "x-portal-apikey: YOUR_API_KEY"

6. Event Markets ​

Get markets for a specific event.

Endpoint: GET /api/v1/events/markets

Query Parameters:

  • event_id (integer, required): Event ID
  • placing (MarketPlacing): LIVE or PREMATCH
  • market_name (MarketName): Market name (1X2, OVER_UNDER, ASIAN_HANDICAP, etc.)
  • bet_type (MarketBetType): BACK or LAY
  • period (MarketPeriod): FULL_TIME or FULL_TIME_AND_OT

Response Structure:

json
{
  "data": [
    {
      "id": 1,
      "event_id": 709,
      "period": "FULL_TIME",
      "bet_type": "BACK",
      "placing": "PREMATCH",
      "market_name": "1X2",
      "value": null,
      "value_type": null,
      "market_books": [
        {
          "market_book_id": 564,
          "market_id": 1,
          "is_open": true,
          "book": "PINNACLE",
          "outcome_0": 2.2,
          "outcome_1": 3.8,
          "outcome_2": 2.1,
          "volume_0": null,
          "volume_1": null,
          "volume_2": null
        }
      ]
    }
  ]
}

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events/markets?event_id=709&placing=PREMATCH&market_name=1X2" \
  -H "x-portal-apikey: YOUR_API_KEY"

7. Markets Feed ​

Get markets for multiple events.

Endpoint: GET /api/v1/markets/feed

Query Parameters:

  • event_ids (string, required): Comma-separated event IDs (max 100 items)
  • page (integer): Page number (default: 0)
  • placing (MarketPlacing): LIVE or PREMATCH
  • market_name (MarketName): Market name
  • bet_type (MarketBetType): BACK or LAY
  • period (MarketPeriod): FULL_TIME or FULL_TIME_AND_OT

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/markets/feed?event_ids=845,123,435,22,842,844,845&placing=PREMATCH&market_name=1X2" \
  -H "x-portal-apikey: YOUR_API_KEY"

8. Markets Books ​

Get detailed market book information.

Endpoint: GET /api/v1/markets/markets-books

Query Parameters:

  • market_book_ids (string, required): Comma-separated market book IDs (max 300 items)

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/markets/markets-books?market_book_ids=56,572,932,22" \
  -H "x-portal-apikey: YOUR_API_KEY"

9. Markets History ​

Get historical odds changes for a specific market book.

Endpoint: GET /api/v1/markets/history

Query Parameters:

  • market_book_id (integer, required): Market book ID

Response Structure:

json
{
  "data": [
    {
      "market_book_id": 564,
      "is_open": true,
      "change_at": "2024-06-25 22:00:00.000",
      "outcome_0": 2.2,
      "outcome_1": 3.8,
      "outcome_2": 2.1,
      "volume_0": null,
      "volume_1": null,
      "volume_2": null
    }
  ]
}

Note: Only modified data is shown. If a value is null, it has not been changed.

Example Request:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/markets/history?market_book_id=564" \
  -H "x-portal-apikey: YOUR_API_KEY"

Step-by-Step Examples ​

Example 1: Getting Started with Football Matches ​

This example shows how to find upcoming football matches and their odds.

Step 1: Get sports to find football

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/sports" \
  -H "x-portal-apikey: YOUR_API_KEY"

Expected response will include:

json
{
  "id": 1,
  "name": "Football",
  "slug": "football"
}

Step 2: Get football tournaments

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/tournaments?sport_id=1&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

Step 3: Get upcoming football events

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?sport_id=1&status=SCHEDULED&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

Step 4: Get odds for a specific event

Replace EVENT_ID with an actual event ID from the previous response:

bash
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events/markets?event_id=EVENT_ID&placing=PREMATCH" \
  -H "x-portal-apikey: YOUR_API_KEY"

Example 2: Finding Live Betting Opportunities ​

This example shows how to find live events and their current odds.

bash
# Get all live events
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?status=LIVE&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

# Get live markets for specific events
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/markets/feed?event_ids=709,845,123&placing=LIVE" \
  -H "x-portal-apikey: YOUR_API_KEY"

Example 3: Tracking Odds Movement ​

This example shows how to track historical odds changes.

bash
# First, find a market_book_id from event markets
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events/markets?event_id=709&placing=PREMATCH" \
  -H "x-portal-apikey: YOUR_API_KEY"

# Then get the history for a specific market book
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/markets/history?market_book_id=564" \
  -H "x-portal-apikey: YOUR_API_KEY"

Example 4: Finding Specific Tournament Events ​

This example shows how to find events for a specific tournament.

bash
# First, find the tournament ID
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/tournaments?sport_id=1&name=Premier%20League" \
  -H "x-portal-apikey: YOUR_API_KEY"

# Then get events for that tournament
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?tournament_id=1&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

Example 5: Working with Date Ranges ​

This example shows how to find events within a specific date range.

bash
# Get events between July 10 and July 15, 2024
curl -X GET "https://odds-feed-api.hgapi.top/api/v1/events?start_at_min=2024-07-10%2000:00:00&start_at_max=2024-07-15%2023:59:59&page=0" \
  -H "x-portal-apikey: YOUR_API_KEY"

Data Structures ​

Sport ​

json
{
  "id": 1,
  "name": "Football",
  "slug": "football"
}

Category ​

json
{
  "id": 1,
  "name": "Brazil",
  "slug": "brazil",
  "code": "br"
}

Tournament ​

json
{
  "id": 1,
  "name": "Premier League",
  "slug": "premier-league"
}

TournamentDetails ​

json
{
  "id": 1,
  "name": "Premier League",
  "slug": "premier-league",
  "category": {
    "id": 1,
    "name": "England",
    "slug": "england",
    "code": "gb"
  },
  "sport": {
    "id": 1,
    "name": "Football",
    "slug": "football"
  }
}

Season ​

json
{
  "id": 1,
  "slug": "2023-2024",
  "year_start": 2023,
  "year_end": 2024
}

SeasonDetails ​

json
{
  "id": 1,
  "slug": "2023-2024",
  "year_start": 2023,
  "year_end": 2024,
  "sport": {
    "id": 1,
    "name": "Football",
    "slug": "football"
  },
  "tournament": {
    "id": 1,
    "name": "Premier League",
    "slug": "premier-league"
  }
}

Team ​

json
{
  "id": 1,
  "name": "Sao Paulo",
  "slug": "sao-paulo",
  "team_type": "TEAM"
}

Event ​

json
{
  "id": 709,
  "sport": {
    "id": 1,
    "name": "Football",
    "slug": "football"
  },
  "category": {
    "id": 1,
    "name": "Brazil",
    "slug": "brazil"
  },
  "tournament": {
    "id": 1,
    "name": "Serie A",
    "slug": "serie-a"
  },
  "season": {
    "id": 1,
    "slug": "2024",
    "year_start": 2024
  },
  "team_home": {
    "id": 1,
    "name": "Sao Paulo",
    "slug": "sao-paulo",
    "team_type": "TEAM"
  },
  "team_away": {
    "id": 2,
    "name": "Palmeiras",
    "slug": "palmeiras",
    "team_type": "TEAM"
  },
  "status": "FINISHED",
  "status_details": "FINISHED",
  "start_at": "2024-06-25 22:00:00.000",
  "winner": "HOME_WIN",
  "score_home": 2,
  "score_away": 1,
  "score_details": "Started: Live",
  "comments": "2024-06-25 22:00:00.000",
  "final_result_only": false,
  "main_outcome_0": 2.2,
  "main_outcome_1": 3.8,
  "main_outcome_2": 2.1,
  "main_volume_1": 2495,
  "main_volume_2": 5495
}

MarketBook ​

json
{
  "market_book_id": 564,
  "market_id": 1,
  "is_open": true,
  "book": "PINNACLE",
  "outcome_0": 2.2,
  "outcome_1": 3.8,
  "outcome_2": 2.1,
  "volume_0": null,
  "volume_1": null,
  "volume_2": null
}

MarketRelated ​

json
{
  "id": 1,
  "event_id": 709,
  "period": "FULL_TIME",
  "bet_type": "BACK",
  "placing": "PREMATCH",
  "market_name": "1X2",
  "value": null,
  "value_type": null,
  "market_books": [
    {
      "market_book_id": 564,
      "market_id": 1,
      "is_open": true,
      "book": "PINNACLE",
      "outcome_0": 2.2,
      "outcome_1": 3.8,
      "outcome_2": 2.1,
      "volume_0": null,
      "volume_1": null,
      "volume_2": null
    }
  ]
}

HistoryOdds ​

json
{
  "market_book_id": 564,
  "is_open": true,
  "change_at": "2024-06-25 22:00:00.000",
  "outcome_0": 2.2,
  "outcome_1": 3.8,
  "outcome_2": 2.1,
  "volume_0": null,
  "volume_1": null,
  "volume_2": null
}

PaginationModel ​

All paginated endpoints follow this structure:

json
{
  "total": 500,
  "per_page": 20,
  "current_page": 0,
  "last_page": 25,
  "data": []
}

Common Use Cases ​

1. Building a Sports Betting Dashboard ​

Goal: Display upcoming matches with odds from multiple bookmakers

Workflow:

  1. Get available sports
  2. Filter for desired sport (e.g., football)
  3. Get scheduled events
  4. Get markets for each event
  5. Display odds from multiple bookmakers

2. Live Odds Monitoring ​

Goal: Monitor real-time odds changes during live events

Workflow:

  1. Get live events
  2. Get live markets for events
  3. Poll for updates regularly
  4. Track odds changes using the history endpoint

3. Historical Analysis ​

Goal: Analyze odds movements and trends

Workflow:

  1. Find completed events
  2. Get market history for each event
  3. Analyze odds changes over time
  4. Identify patterns and trends

4. Arbitrage Detection ​

Goal: Find arbitrage opportunities across bookmakers

Workflow:

  1. Get events and markets
  2. Compare odds across different bookmakers
  3. Calculate arbitrage opportunities
  4. Alert when favorable conditions exist

5. Odds Comparison ​

Goal: Compare odds across multiple bookmakers

Workflow:

  1. Get events and markets
  2. For each market, compare odds across bookmakers
  3. Display the best available odds
  4. Track odds changes

Best Practices ​

Error Handling ​

Always implement proper error handling:

bash
# Example error response
{
  "detail": [
    {
      "loc": ["query", "sport_id"],
      "msg": "ensure this value is greater than or equal to 1",
      "type": "value_error.number.not_ge"
    }
  ]
}

Rate Limiting ​

Be mindful of rate limits when making multiple requests. Implement proper retry logic with exponential backoff.

Data Caching ​

Cache frequently accessed data like sports, categories, and tournaments to reduce API calls.

Date Formatting ​

Always use UTC timezone and format dates as: YYYY-MM-DD HH:MM:SS.000

Event IDs ​

Keep track of event IDs you're interested in for efficient querying.

Pagination ​

Use pagination effectively by:

  • Starting with page=0
  • Checking the last_page value
  • Iterating through pages as needed

Support ​

If you have questions or need assistance:

Additional Resources ​

We’re dedicated to providing the best API products.

API by Tipsters CO © All Right Reserved