External Fixture Feed Integration
- Aleksander Puumets
- Santiago Montoya Varela
- Tonis Danilson
Introduction
We have the ability to integrate external Fixture feeds, enabling us to make the external Fixture Id accessible through both the Booking API and include it in the Fixture Creation message that we will generate.
Timelines
Development work usually takes up to two weeks from the initial request. If there are any changes to the timelines, we will promptly notify you.
Requirements:
In order to seamlessly integrate your external Fixture feeds, our Fixture Acquisition development team needs the following criteria to be fulfilled. Please be aware that integrating a fixture feed may take up to two weeks. Therefore, any changes in feed source or availability should be communicated well in advance, allowing our team enough time to implement the required adjustments for uninterrupted use of your feed:
Documentation.
This is crucial. Each feed represents a new world, making it essential for us to swiftly comprehend the data structure, responses, and other key details, such as endpoints. Documentation plays a pivotal role as we've observed that inadequate documentation leads to increased time spent understanding the client's endpoint rather than on the Integration process itself.
This serves as an example of how the documentation should be presented:
Endpoint URL.
This serves as our entry point, through which all information flows. An illustration of a typical URL is https://contentgraph.media.api.geniussports.com.
Authentication Details
This delineates the security level linked to your feed's endpoint when we attempt to access the data. Below, we outline some of the most commonly used authentication methods:
None: In this scenario, you can simply specify that no authentication is required.
Username and Password: This method involves using a username and password for accessing all the data.
API Key: This method utilizes a unique identifier for Genius and functions as an authentication mechanism where only authorized API Keys can access your data. An example of an API key might look like zaCELgL.0imfnc8mVLWwsA.
API Token: Similar to the API Key, this is a unique identifier for Genius on the client's end; however, token generation may necessitate an additional endpoint which is typically documented by the client using numbers, letters, and special characters in these tokens.
Client Secret: Exclusive to each user, this unique identifier is provided by the client so that Genius can access their information. The Client Secret usually accompanies a ClientId in generating a token—a more advanced authentication process.
IP whitelisting.
The IP addresses listed below must be whitelisted to enable us to access your feed:
52.214.13.88
34.253.169.237
Feed requirements.
The feed can be in the format of either an XML/JSON feed or a Pull API. For successful integration of the feed, the following data must be available.
Sport or Sport Id
Competition name & Competition Id
Fixture name & Fixture Id
Fixture start time
Home competitor name & Id
Away competitor name & Id
Additionally, if you would also like us to integrate your Odds data, then the following will need to be available for all fixtures:
Market name & Id
Selection name & Id
Odds per Selection
Feed Example
Below you can find an example of what we would expect there to be in the feed - the example features one fixture and one market:
<group id="240" name="Football">
<group id="141078497" name="England">
<group id="6323610" name="ENG Premier League">
<group id="998598200" name="Bournemouth v Manchester United">
<market name="3 Way Handicap (1) [90 Mins]" id="130433112" expiry="2018-11-03T12:30:00Z" inRunning="false">
<selection name="Bournemouth (+1)" id="59805551700" handicap="1.0" price="1.775" selectionLinkInfo="59805551700/415013750202"/>
<selection name="Manchester United (-1)" id="59805552600" handicap="-1.0" price="3.7" selectionLinkInfo="59805552600/415013750002"/>
<selection name="Handicap Tie - Bournemouth +1" id="59805553200" handicap="" price="3.75" selectionLinkInfo="59805553200/415013749902"/>
</market>External Fixture Id via the Booking API
Once the external Fixture feed has been successfully integrated, your Fixture Id’s will become available through the Booking API. More information about the Booking API itself can be found on the following Confluence page.
The external Fixture Id will however be present within the External Id’s array.
The source id will be id the we allocate to your external Fixture feed after we have integrated it, which will differ from your Bookmaker Id that will be present for instance in the Fixture messages.
An example can be found below:
{
"FixtureId": 5242621,
"CompetitionId": 198,
"CompetitionName": "Uruguay Primera División",
"SportId": 10,
"Name": "CA Cerro v CA Peñarol",
"Date": "2018-03-21T19:00:00Z",
"CustomerFixtureId": "14124225", - this field has now been deprecated
"IsBooked": true,
"AvailableFeeds": [
{
"Name": null,
"Type": "MatchState",
"IsLicensed": true,
"Metadata": {
"Origin": "Venue",
"Lineups": "False",
"Multisport": "False"
}
},
{
"Name": null,
"Type": "TradingState",
"IsLicensed": true,
"Metadata": null
}
],
"ExternalIds": [
{
"Source": "1000",
"Id": "14124225"
},
{
"Source": "1001",
"Id": "2747471"
}
]
}External Fixture Id via the Fixture Creation message
Once the external Fixture feed has been successfully integrated, your Fixture Id’s will become available and will be present within our Fixture Creation messages. More information about the Booking API itself can be found on the following Confluence page.
The external Fixture Id will be be available in the ExternalId element - a truncated example of the Fixture creation message you would expect to receive would be as follows - the full message is available in the aforementioned Confluence page which details the structure of our Fixture creation messages.
The example is as follows:
<?xml version="1.0" encoding="utf-8"?>
<Updategram xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.sportsdataservices.com/integrationService/v3">
<Header>
<MessageGuid>6a39609c-5d82-45b4-8ff0-d409286b90c1</MessageGuid>
<TimeStampUtc>2018-04-12T19:06:57.344251Z</TimeStampUtc>
<Retry>0</Retry>
<ChannelId>7026</ChannelId>
</Header>
<Fixture>
<Id>5235368</Id>
<Name>Olympique Marseille v RB Leipzig</Name>
<FixtureType>Match</FixtureType>
<Status>Scheduled</Status>
<StartTimeUtc>2018-04-12T19:05:00Z</StartTimeUtc>
<Sport>
<Id>10</Id>
<Name>Football</Name>
</Sport>
<Competition>
<Id>2072</Id>
<Name>UEFA Europa League</Name>
<Region>
<Id>6</Id>
<Name>Europe</Name>
</Region>
</Competition>
<Season>
<Id>64680</Id>
<Name>UEFA Europa League 2017 2018</Name>
</Season>
<Round>
<Id>398950</Id>
<Name>Olympique Marseille v RB Leipzig</Name>
</Round>
<Competitors>
...
</Competitors>
<AggregateEventInfo/>
<ExternalId>1659322</ExternalId>
<FootballProperties>
<ExtraTimeProperties>
<IsExtraTime>true</IsExtraTime>
<IsSecondLeg>true</IsSecondLeg>
<FirstLegId>5235367</FirstLegId>
<AwayGoalsAfterNormalTime>true</AwayGoalsAfterNormalTime>
<AwayGoalsAfterExtraTime>true</AwayGoalsAfterExtraTime>
</ExtraTimeProperties>
<MatchDuration>PT1H30M</MatchDuration>
<ExtraTimeDuration>PT30M</ExtraTimeDuration>
</FootballProperties>
</Fixture>
</Updategram>
FAQs
What is the preferred format type for feeds?
When it comes to integrating feeds, JSON is the preferred choice due to its faster processing compared to XML formats.
Why is Documentation Required During Feed Creation?
When a new feed request is received, requests lacking documentation on how to consume the feed may be rejected as we are unable to determine the method of consumption.
The Purpose of Including Competitions in Feed Creation
Feeds typically contain a wealth of information, and not all of it is relevant for integration. It's crucial to clearly specify the required competitions. Requesting the integration of all football (or multiple specific sports) competitions is acceptable, but requesting integration of every single competition in the feed is not.
The Reason for Requesting IP Whitelisting During Feed Creation
If our IPs are not whitelisted, there is a possibility of us being blocked. Failure to whitelist beforehand could potentially result in delays in the feed creation process.