tutorial

How to Choose Decimal Odds Format at Integration Time

By Daniel

When you're pulling pre-match football odds into your application, the format of those odds matters. Most developers prefer decimal odds for programmatic use because they simplify calculations and comparisons. This guide will show you how to choose decimal odds format at integration time with a reliable UK bookmaker odds API like ukoddsapi.com, ensuring your data is ready for immediate use.

Integrating pre-match football odds JSON into your system should be straightforward. You need a consistent, clean data feed that avoids the headaches of scraping individual bookmaker sites. A dedicated odds API provides this, offering normalised data across multiple UK bookmakers. Understanding how to specify your preferred odds format from the start simplifies your data processing pipeline and reduces conversion logic in your application. This tutorial focuses on getting your data in decimal format, explaining why it's the standard for many betting applications.

a digital interface showing various odds formats being converted to decimal, with code snippets in the background

Prerequisites

Before you can integrate pre-match football odds and specify their format, you'll need a few things set up:

  • ukoddsapi.com API Key: You'll need an active API key to authenticate your requests. If you don't have one, you can sign up for a free account on the ukoddsapi.com website.
  • Programming Language: This tutorial uses Python, a common choice for data-driven applications. The concepts apply to other languages like JavaScript or Node.js as well.
  • HTTP Client Library: For Python, we'll use the requests library. For Node.js, fetch is built-in.
  • Basic API Knowledge: Familiarity with making HTTP GET requests and parsing JSON responses is assumed.

This setup ensures you can connect to the API, retrieve data, and process it efficiently.

Step 1: Fetching Pre-Match Events

The first step in any odds integration is to identify the football fixtures you're interested in. The GET /v1/football/events endpoint allows you to retrieve a list of scheduled matches for a specific date. This is where you'll get the event_id needed to fetch detailed odds.

Here's how you'd make that request in Python:

import os
import requests
from datetime import date, timedelta

# Replace with your actual API key
API_KEY = os.environ.get("UKODDSAPI_KEY", "YOUR_API_KEY")
BASE_URL = "https://api.ukoddsapi.com"
HEADERS = {"X-Api-Key": API_KEY}

# Get events for tomorrow
tomorrow = date.today() + timedelta(days=1)
schedule_date = tomorrow.strftime("%Y-%m-%d")

try:
    events_response = requests.get(
        f"{BASE_URL}/v1/football/events",
        headers=HEADERS,
        params={"schedule_date": schedule_date, "has_odds": "true", "per_page": "5"},
        timeout=30,
    )
    events_response.raise_for_status() # Raise an exception for HTTP errors
    events_data = events_response.json()

    if events_data and events_data.get("events"):
        print(f"Found {len(events_data['events'])} events for {schedule_date}:")
        for event in events_data["events"]:
            print(f"  Event ID: {event['event_id']}, Match: {event['home_team']} vs {event['away_team']}")
        
        # Store the first event_id for the next step
        first_event_id = events_data["events"][0]["event_id"]
        print(f"\nUsing first event ID: {first_event_id}")
    else:
        print(f"No events with odds found for {schedule_date}.")
        first_event_id = None

except requests.exceptions.RequestException as e:
    print(f"Error fetching events: {e}")
    first_event_id = None

This Python snippet fetches up to five football events scheduled for tomorrow that have associated odds. It then prints a summary of these events, including their unique event_id. The has_odds=true parameter filters for events where pre-match odds are already available, which is useful for ensuring you only process relevant fixtures. The per_page=5 parameter limits the number of events returned, which is good practice for initial testing and to manage API usage. If events are found, it extracts the event_id of the first match, which we'll use in the next step to retrieve its specific odds.

{
  "schema_version": "1.0",
  "count": 5,
  "events": [
    {
      "event_id": "EVT001234567890",
      "league_name": "Premier League",
      "home_team": "Arsenal",
      "away_team": "Chelsea",
      "kickoff_utc": "2026-04-26T15:00:00Z",
      "markets_with_odds": ["match_winner", "over_under_2_5_goals"],
      "unique_bookmaker_codes": ["UO001", "UO003", "UO027"]
    },
    {
      "event_id": "EVT001234567891",
      "league_name": "Championship",
      "home_team": "Leeds United",
      "away_team": "Leicester City",
      "kickoff_utc": "2026-04-26T12:30:00Z",
      "markets_with_odds": ["match_winner"],
      "unique_bookmaker_codes": ["UO001", "UO002"]
    }
  ],
  "note": "Response truncated for brevity."
}

The JSON response provides a list of events, each with a unique event_id, team names, kickoff time, and a summary of available markets and bookmakers. This event_id is the key to drilling down and getting the detailed pre-match odds for that specific fixture.

Step 2: Requesting Odds in Decimal Format

Once you have an event_id, you can request the full pre-match odds for that fixture using the GET /v1/football/events/{event_id}/odds endpoint. This is where you explicitly tell the API how to choose decimal odds format at integration time. You do this by setting the odds_format query parameter to decimal.

Here's the Python code to fetch odds for the event_id obtained in Step 1, ensuring you get pre-match football odds JSON in decimal format:

# Assuming first_event_id was successfully obtained from Step 1
if first_event_id:
    try:
        odds_response = requests.get(
            f"{BASE_URL}/v1/football/events/{first_event_id}/odds",
            headers=HEADERS,
            params={"package": "core", "odds_format": "decimal"},
            timeout=60,
        )
        odds_response.raise_for_status()
        odds_data = odds_response.json()

        if odds_data:
            print(f"\nOdds for {odds_data.get('event_title')} (Event ID: {first_event_id}):")
            # Example: Print odds for the Match Winner market
            for market in odds_data.get("markets", []):
                if market["market_name"] == "Match Winner":
                    print(f"  Market: {market['market_name']}")
                    for selection in market.get("selections", []):
                        # Filter to show only one bookmaker for brevity
                        bookmaker_odds = [
                            o for o in selection["odds"] if o["bookmaker_code"] == "UO027"
                        ]
                        if bookmaker_odds:
                            print(f"    Selection: {selection['selection_name']}, Odds (William Hill): {bookmaker_odds[0]['price']}")
                        else:
                            print(f"    Selection: {selection['selection_name']}, No odds from William Hill.")
                    break # Only show Match Winner for this example
        else:
            print(f"No odds data found for event ID: {first_event_id}")

    except requests.exceptions.RequestException as e:
        print(f"Error fetching odds: {e}")

This code makes a request for the odds of a specific event. The key part is params={"package": "core", "odds_format": "decimal"}. This tells the API to return odds in decimal format. The package parameter specifies the market coverage, with core providing standard markets like Match Winner. The response is then parsed, and we extract and print the decimal odds for a specific selection from a particular bookmaker (William Hill, UO027 in this example). This demonstrates the direct access to formatted odds.

{
  "schema_version": "1.0",
  "event_id": "EVT001234567890",
  "event_title": "Arsenal vs Chelsea",
  "kickoff_utc": "2026-04-26T15:00:00Z",
  "summary": {
    "league_name": "Premier League",
    "home_team": "Arsenal",
    "away_team": "Chelsea"
  },
  "markets": [
    {
      "market_id": "MKT001",
      "market_name": "Match Winner",
      "market_group": "main",
      "selection_count": 3,
      "selections": [
        {
          "selection_name": "Arsenal",
          "line": null,
          "odds": [
            { "bookmaker_code": "UO001", "price": 1.85, "status": "active" },
            { "bookmaker_code": "UO003", "price": 1.90, "status": "active" },
            { "bookmaker_code": "UO027", "price": 1.80, "status": "active" }
          ]
        },
        {
          "selection_name": "Draw",
          "line": null,
          "odds": [
            { "bookmaker_code": "UO001", "price": 3.50, "status": "active" },
            { "bookmaker_code": "UO003", "price": 3.40, "status": "active" },
            { "bookmaker_code": "UO027", "price": 3.60, "status": "active" }
          ]
        },
        {
          "selection_name": "Chelsea",
          "line": null,
          "odds": [
            { "bookmaker_code": "UO001", "price": 4.20, "status": "active" },
            { "bookmaker_code": "UO003", "price": 4.00, "status": "active" },
            { "bookmaker_code": "UO027", "price": 4.33, "status": "active" }
          ]
        }
      ]
    }
  ],
  "note": "Response truncated for brevity."
}

The markets array in the JSON response contains various betting markets. Each selection within a market has an odds array, where each object represents a bookmaker's price. Notice how the price field directly provides the decimal odds format (e.g., 1.85, 3.50, 4.33), ready for your application's logic. This eliminates the need for any client-side conversion, streamlining your how to choose decimal odds format at integration time integration.

Step 3: Processing and Displaying Decimal Odds

Once you have the pre-match football odds JSON in decimal format, your application can process and display them. This might involve finding the best odds across bookmakers, calculating implied probabilities, or feeding the data into a comparison table. Since the data is already in a consistent numerical format, these operations are straightforward.

Let's expand on the previous example to find the best decimal odds for each selection in the "Match Winner" market:

if odds_data:
    print(f"\nProcessing odds for {odds_data.get('event_title')}:")
    for market in odds_data.get("markets", []):
        if market["market_name"] == "Match Winner":
            print(f"  Market: {market['market_name']}")
            for selection in market.get("selections", []):
                best_price = 0.0
                best_bookmaker = "N/A"
                
                for bookmaker_odd in selection["odds"]:
                    if bookmaker_odd["status"] == "active" and bookmaker_odd["price"] > best_price:
                        best_price = bookmaker_odd["price"]
                        best_bookmaker = bookmaker_odd["bookmaker_code"]
                
                print(f"    Selection: {selection['selection_name']}")
                print(f"      Best Decimal Odd: {best_price} (from {best_bookmaker})")
            break # Only process Match Winner for this example

This code iterates through the "Match Winner" market and for each selection (e.g., "Arsenal", "Draw", "Chelsea"), it finds the highest decimal odd available across all bookmakers. This is a common requirement for odds comparison sites or arbitrage tools. The direct numerical values make this calculation simple and efficient. The odds API without scraping provides this clean data, saving significant development time.

The consistency of decimal odds simplifies further calculations:

  • Implied Probability: 1 / decimal_odd
  • Arbitrage Detection: Sum of 1 / decimal_odd for all outcomes should be less than 1.
  • Odds Comparison: Direct numerical comparison to find the highest price.

This final step demonstrates the power of receiving data in your preferred format directly from the API. It streamlines your backend logic and ensures accuracy, making your integration robust and easy to maintain.

Common Mistakes

Integrating with any API can have its quirks. When dealing with pre-match football odds and specifying formats, here are some common pitfalls to avoid:

  • Forgetting odds_format parameter: If you don't specify odds_format=decimal, the API might default to another format or return an error depending on its configuration. Always explicitly state your preference.
  • Incorrect event_id: Using an event_id that doesn't exist, is malformed, or belongs to an event without available odds will result in an empty or error response. Always validate event_id from the /events endpoint.
  • Ignoring API rate limits: Rapid, successive requests without delays will quickly hit rate limits. Implement proper backoff strategies and caching. The ukoddsapi.com free tier has a limit of 300 requests/month, while paid tiers offer higher limits like 1,000 or 5,000 requests/hour.
  • Hardcoding bookmaker IDs: Bookmaker codes like UO001 are stable, but relying on their order or assuming specific bookmakers are always present can lead to brittle code. Always iterate through the bookmakers list or check for specific codes.
  • Misinterpreting "live" odds: UK Odds API provides pre-match odds. Do not expect real-time, in-play updates. The data represents snapshots of prices before kickoff. If you need updated pre-match prices, poll the API at sensible intervals.
  • Not handling missing data: Not all bookmakers will offer odds for every selection, or an event might temporarily have no odds. Your code should gracefully handle empty odds arrays or null values.

Options and Alternatives

When it comes to obtaining pre-match football odds, developers have several approaches. Each has trade-offs in terms of effort, reliability, and data quality. Choosing decimal odds format at integration time is just one aspect of this decision.

Feature / Approach ukoddsapi.com (API) Direct Scraping (DIY) Generic Global Odds API (e.g., The Odds API)
Odds Format Control Direct odds_format=decimal parameter Requires custom parsing/conversion logic Varies by provider; often supports multiple formats
Data Reliability High; managed by API provider, consistent JSON Low; prone to breaking changes on source sites Varies by provider; generally good for global coverage
UK Bookmaker Coverage Excellent (27+ UK bookmakers) Limited by effort; difficult to maintain many sources May be weaker for specific UK-only bookmakers
Effort to Integrate Low; single endpoint, normalised data Very High; building & maintaining parsers, proxies Moderate; often good docs, but may need data mapping
Cost Tiered pricing (free to business) High (proxies, infrastructure, dev time) Varies; often higher for UK-specific depth
Data Latency Updated snapshots (pre-match) Varies; depends on scraper speed & frequency Varies; often good for pre-match, some in-play available
Legal / ToS Clear API terms of service Often violates website ToS; legal risks Clear API terms of service

Using a dedicated UK bookmaker odds API like ukoddsapi.com offers a significant advantage, especially when you need specific data like pre-match football odds JSON in a consistent decimal format. It removes the burden of maintaining complex scraping infrastructure and dealing with constant website changes, allowing you to focus on building your application. While direct scraping might seem free, the hidden costs in development and maintenance time are substantial. Generic global APIs might cover many sports, but often lack the depth of UK-specific bookmaker coverage that ukoddsapi.com provides.

FAQ

Can I request other odds formats besides decimal?

Yes, ukoddsapi.com supports other common odds formats. While decimal is often preferred for programmatic use, you might be able to request fractional or moneyline formats depending on the API's capabilities. Always check the official API documentation for supported odds_format values.

What if a bookmaker doesn't offer decimal odds for a specific selection?

If a bookmaker only provides odds in a different format, the API will typically convert it to your requested decimal format. If no odds are available at all, that bookmaker's entry for that selection might be missing or show a null price. Your integration should handle these cases gracefully.

How often are the pre-match odds updated?

Pre-match odds are updated regularly by ukoddsapi.com to reflect changes from bookmakers before kickoff. The exact frequency can vary, but the API provides fresh snapshots. This is not an in-play feed, so sub-second updates are not the expectation; rather, it's about getting the latest pre-match prices.

How do I handle missing odds for a selection or an entire market?

Your code should always anticipate missing data. When iterating through markets or selections, check if the odds array is empty or if price values are null. Implement conditional logic to skip these or display a "N/A" message to prevent errors in your application.

What's the best way to store these decimal odds in a database?

For storing decimal odds, use a floating-point number type in your database (e.g., DECIMAL(5,2) or FLOAT in SQL, or a Number type in NoSQL databases). Be mindful of floating-point precision issues if performing critical financial calculations, and consider storing price as a string or integer (multiplied by 100) if exact precision is paramount.

Choosing how to choose decimal odds format at integration time is a fundamental decision that impacts your entire data pipeline. By leveraging a robust UK bookmaker odds API like ukoddsapi.com, you get clean, consistent pre-match football odds JSON directly in the format you need. This approach saves countless hours compared to building an odds API without scraping from scratch, allowing you to focus on building innovative applications.

Get started with your pre-match football odds integration today at ukoddsapi.com.