Fixtures API V2

Overview

Welcome to the Fixtures API v2 documentation!

What is Fixtures API v2?

This API allows you to access specific information about sports, competitions, seasons, sport events, players, and related concepts from the Genius Sports Fixtures master data.

For what use cases you can use Fixtures API v2?

1. Read Data

When to use it?

When you want to retrieve various details related to fixture schedules, such as:

• Scheduled competitions in a sport

• Events within a competition

• Fixture-specific information

• Players in teams

• Other Fixture Schedule-related information

Examples:

• Discover who is playing in a particular fixture.

  • Example: Real Madrid vs. Barcelona

• Find out when and where a sport event (fixture) is happening.

  • Example: 22.08.2024 at 19:00 at Santiago Bernabeu

• Learn about specific sport-specific rules of the game.

  • Example: Extra time applied

2. Ingest Data in Genius Sports

When to use it?

When you need to integrate your competitions, fixtures and associated data directly into the Genius Sports Fixtures master data. This streamlines the integration process as all necessary internal procedures, including validation, matching, and state management, are handled internally by Genius Sports.

If you have permissions, it will automatically update the data in Genius Sports side. Otherwise, it will be pending for approvals.

Examples:

1. Ingest your data about particular competition and fixtures in it.

• Competition: Spain La Liga

• Fixture: Real Madrid vs. Barcelona

• Competitors: Real Madrid, Barcelona

• Start date and time: 22.08.2024 at 19:00

• Venue: Santiago Bernabeu

2. Update start time of Real Madrid vs. Barcelona to 19:15

3. Send the contracted players with their metadata per team e.g. Real Madrid with players: Daniel Carvajal Ramos (Date of Birth: 1991-07-01, Male, …), Lucas Vazquez Iglesias (…), etc.

3. Update Genius Sports data

When to use it?

If you require modifying Genius Sports Fixtures data that cannot be done through ingestion, such as Competition Name, Competitor Name, or Venue, your data must adhere to Genius Sports' specific structure, which can be seen below and in the API endpoints. To utilize these functionalities, you need a Genius Sports ID, obtainable through the Ingestion endpoint by tracking the results. Depending on your permissions' level, you can undertake actions like:

• Updating existing records

• Removing outdated or incorrect entries

If you have permissions, it will automatically update the data in Genius Sports side. Otherwise, it will be pending for approvals.

Examples:

After ingesting data through Ingestion and obtaining the Genius Sports ID for a competition and fixture, if you wish to update the venue you can do that by sending that information. For example adding country “Spain” to “Santiago Bernabeu” venue.

How is our data Structured?

Our data is organized according to the following primary properties, forming our Fixtures Hierarchy. Each of these properties can be accessed through the corresponding endpoints of the API.

• sports

  • competitions

    • seasons

      • rounds

        • fixtures

          • fixture competitors

            • competitor

• person

To understand the interconnections of the data, you can use this Entity-Relation Diagram

What is new in Fixtures API v2?

• Consistent pagination with up to 200 items per page

• Sorting by specific field(s) for example by id, name, descending

• Filter by specific fields

  • For single ID filtering: Example: filter=id[equals]:1

  • For filtering by multiple IDs: Example: filter=id[in]:1,2,3

  • For stacking filters: Separate them with "". Example: filter=id[in]:1,2,3sportId[in]:1,2,3,4,5

  • Different filter comparators available:

    • equals: Matches exact values of all data types

    • notequals: Filters out values not matching the specified criteria

    • in: Matches values from a specified list, works only with integer and decimal values

    • nin: Excludes values from a specified list, works only with integer and decimal values

    • gte: Greater than or equal to comparator

    • lte: Less than or equal to comparator

    • contains: Matches values containing a specified substring

    • startsWith: Matches values starting with a specified substring

    • Duplications of the "filter" property are allowed only in the case of "range" filtering, such as filter=startDate[gte]:2021-07-28~startDate[lte]:2021-07-29

    • filtering by null:

      • Equal to null: filter=cityName[equals]:null

      • Not equal to null: filter=cityName[notequals]:null

• The API maintains a uniform structure, with each endpoint offering two functionalities:

  • A listing endpoint for multiple items, enabling filtering and sorting via query parameters.

  • An endpoint dedicated to retrieving a single item using its unique identifier (ID).

• The API doesn’t contain deleted fixtures

• New “Person” entity introduced: Person is a representation of a real-life person which can be used in specific context:

  • For Competitors of type Player it is the person behind the player.

  • For Competitors of type Team it is part of their squad, or is the coach, or the owner.

  • For Competitors of type Doubles Partnership it is the persons behind the Doubles Partnership or their coach.

  • For Competitors of type Dog and Horse it is the trainer, the owner or the breeder.
    - For Competitors of type Horses it could also be its Jockey

  • For FixtureOfficials either Official Referee or Assistant Referee

• In the Fixtures API v2, we support rosters (also known as "Squads"), which represent a list of all players registered to a team and available for selection in each fixture. However, the API does not support lineups, which refer to specific players participating in a particular fixture.

How to Start with Fixtures API v2?

Access to Fixture API V2

To access the Fixture API V2 you will need to use an Auth0 Client (client Secret and clientId) and API key supplied by Genius Sports. Please contact your integration manager for further details. 

Steps to call the API

Call the Auth API to get a Token: 

• Take the "access_token" returned by the auth call and add it as the "Authorization" header with the value “Bearer{access_token}“ in the API call you are going to make to Fixtures API V2

• Add your API key as the "x-api-key" header in the call to Fixtures API V2 also

• Call FixturesAPI V2

Sample API calls demonstrating how to utilize the API for particular use cases

Use case “Read Data”

Find the sport

First step is to find the sport you are licensed to receive or is relevant to your current work. The following examples will all be from American Football:

The return will be all sports covered by Genius Sports and their corresponding sportId. The sportId for American Football = 17

Find the competition

Once you have the sportId/sportName you can search for the competition within that sport (i.e. NFL, NCAA, CFL, etc):

In this example, the NFL competition = 296

Find the season

The competition found above = 296 and the 2022/23 NFL season = 108075

Find the fixture

Below is one example fixture from season = 108075 (2022/23 NFL). As you can see, each fixture has the sport, season, locality, gender, competitors, round, date/time, status, and venue.

Use Case “Ingest Data in Genius Sports”

Ingesting a fixture example

• Post call to:

   

  • Request body:

     

  • Response body:

     

Track the status of your ingestion

• GET call to:

   

  • Response

Use Case “Update Genius Sports data”

To Add a Person to a Team

The same Person from the example above is used

• POST call to:
  
  

   

  • Request body:
    
    

     

  • Response:
    
    

The above code examples will get you started on using the Fixture API v2. There are more options for information available and is constantly updated throughout the year. You can find more information on that from the Online documentation section.