Prerequisites
Requesting an API key
Contact your Genius CSM to obtain an API key from the Genius IT team.
Uploading data
Method: POST
Queues a valid set of data for upload in the RevShare database. Once the upload is accepted and response 200 is received, the upload will be queued for full validation by the solution. Final validation information can be received by submitting the GET request shown below.
API Endpoints
UAT
https://uat.revshare.api.geniussports.com/api/uploads/json
Production
https://production.revshare.api.geniussports.com/api/uploads/json
Mandatory parameters
Parameter | Description | Value type |
|---|
uploaded_by | Email address of the uploading client’s contact | string <email> Example:uploaded_by=test.revshare.customer1@geniussports.com |
account_id | Account ID of the client | number Example: account_id=1000004 |
start_date | Start date of the uploaded data | string^\d\d\d\d-\d\d-\d\d$ (YYYY-MM-DD) Example: start_date=2022-09-01 |
end_date | End date of the uploaded data | string^\d\d\d\d-\d\d-\d\d$ (YYYY-MM-DD) Example: end_date=2022-09-30 |
provided_for | RevShare or NFL upload | string Enum: revshare nfl |
template | Account or Brand level NFL or Inplay (RevShare) upload | string Enum: nfl_account nfl_brand inplay_account inplay_brand |
reference | Automated upload reference number or identifier. | string Example: reference=API-Upload-Oct-22 This reference appears on emails sent to the admin contact of the client |
token | Client's Authentication Token | string Example: token=6cfc21c0-7e5b-11ed-a1eb-0242ac121112 |
JSON body expected
You should preferably submit the JSON body with 1000 fixtures per request. A bigger amount of fixtures may cause the API to respond slower than expected. Calls with more than 5000 fixtures may not succeed.
Each fixture must be placed in a separate JSON object. You can expand the fields below to see a full list of properties that must be submitted per fixture.
Please note that the JSON object keys must be lowercase!
NFL Account Level data
{
'fixture_id': '9249617',
'fixture_name': 'Philadelphia Eagles v Washington Commanders',
'fixture_date': '15.11.22 0:00',
'country': 'USA',
'state': 'KS',
'bet_type_level_1': 'Final Score',
'bet_type_level_2': 'Moneyline',
'total_stake': '9897',
'gross_gaming_revenue': '8626',
'inplay_gross_gaming_revenue': '1915',
'number_of_bets': '56',
'unique_bettors': '9',
'pre_game_percent_of_stake': '0.45',
'in_game_percent_of_stake': '0.55',
'pre_game_percent_of_bets': '0.23',
'in_game_percent_of_bets': '0.77',
'online_percent_of_stake': '0.65',
'land_based_percent_of_stake': '0.35',
'median_bet_size': '282.03',
'average_bet_size': '154.03'
}
NFL Brand level data
{
'brand': 'brand_name',
'brand_id': '100123',
'fixture_id': '9249617',
'fixture_name': 'Philadelphia Eagles v Washington Commanders',
'fixture_date': '15.11.22 0:00',
'country': 'USA',
'state': 'KS',
'bet_type_level_1': 'Final Score',
'bet_type_level_2': 'Moneyline',
'total_stake': '9897',
'gross_gaming_revenue': '8626',
'inplay_gross_gaming_revenue': '1915',
'number_of_bets': '56',
'unique_bettors': '9',
'pre_game_percent_of_stake': '0.45',
'in_game_percent_of_stake': '0.55',
'pre_game_percent_of_bets': '0.23',
'in_game_percent_of_bets': '0.77',
'online_percent_of_stake': '0.65',
'land_based_percent_of_stake': '0.35',
'median_bet_size': '282.03',
'average_bet_size': '154.03'
}
InPlay Account level data
{
'sport': 'Basketball',
'sport_id': '4',
'competition': 'FIBA EuroBasket',
'competition_id': '1484',
'fixture_name': 'Ukraine v Italy',
'fixture_id': '8057468',
'fixture_date': '5.09.22 0:00',
'currency': 'GBP',
'gross_gaming_revenue': '17086',
'number_of_bets': '70',
'total_stake': '31302',
'winnings': '0',
'bets_declared_void': '1',
'chargebacks': '2',
'gambling_taxes': '1370',
'net_gaming_revenue': '8718'
}
InPlay Brand level data
{
'brand': 'brand_name',
'brand_id': '100123',
'sport': 'American Football',
'sport_id': '17',
'competition': 'Canada Football League',
'competition_id': '1035',
'fixture_name': 'Ottawa RedBlacks v Hamilton Tiger-Cats',
'fixture_id': '8806761',
'fixture_date': 'Saturday, 29 October 2022',
'currency': 'GBP',
'gross_gaming_revenue': '22156',
'number_of_bets': '108',
'total_stake': '25703',
'winnings': '52',
'bets_declared_void': '2',
'chargebacks': '2',
'gambling_taxes': '755',
'net_gaming_revenue': '8352'
}
Response
The API returns a 200 response when the upload passes first-level validation (full validation is done later by the solution). In case the upload is successful, a JSON body is also returned in the request that also specifies the Upload ID. The Upload ID can later on be used to validate if the upload has any errors.
Example success body
{
"result":"success",
"data":{
"upload_uuid":"8e07139e-25f6-462c-82ed-5b4d123c0a22",
"records_count":1000
}
}
Email Notifications
The API does not send notifications to the RevShare InPlay or NFL contact in case the data uploaded has no errors. In case of errors, the API will notify the RevShare contact that there was an error. The errors will be sent via email for each chunk of data that is loaded. Genius is looking to change this behaviour to one email per upload.
Example Python Function to upload data
The example below uses Python to upload API data. What it does in short:
Ingests a CSV, lowercases all keys and converts it to JSON objects
Submits the data to the API via the upload_revshare_data function which users the requests module. The function takes care of splitting the list of JSON objects to chunks of 1000 (if more than 1000).
The function returns, via print statements, the response of the API
Python code
import requests
import csv
import os
#The actual function that uploads RevShare data.
def upload_revshare_data (
endpoint,
uploaded_by,
account_id,
start_date,
end_date,
provided_for,
template,
reference,
token,
records):
# Set up Params for the Rquests module
params = {
'uploaded_by' : uploaded_by,
'account_id' : account_id,
'start_date' : start_date,
'end_date' : end_date,
'provided_for': provided_for,
'template' : template,
'reference' : reference,
'token' : token
}
#Break down the JSON data in chunks of 1000 items as this is the recommended maximum upload.
chunks = [records[x:x+1000] for x in range(0, len(records), 1000)]
for id, chunk in enumerate(chunks):
#Actual upload via the requests module
upload = requests.post(
url = endpoint,
params = params,
json = chunk
)
if upload.status_code == 200:
print("Succesfully uploaded chunk {0}!".format(id))
print("Response received \n {0}".format(upload._content))
else:
print("An error appeared, error code {0}".format(upload.status_code))
print("Response received \n {0}".format(upload._content))
###Program starts here:
if __name__ == '__main__':
api_key = os.getenv('REVSHARE_API_KEY')
## Load a CSV to upload as JSON
csv_data = []
with open('Entain Account Level NFL 2022 Game week 16 - API.csv', 'r', encoding='utf-8-sig') as file:
csv_reader = csv.DictReader(file)
for row in csv_reader:
csv_data.append(row)
## Lowecase the keys in the JSON records and add them to a new list:
json_data = []
for row in csv_data:
json_data.append({k.lower(): v for k, v in row.items()})
###Some preliminary knowns:
endpoint = 'https://uat.revshare.api.geniussports.com/api/uploads/json'
uploaded_by = 'xxxxx.xxxxx@geniussports.com'
## Template: nfl_account, nfl_brand, inplay_account, inplay_brand
template = 'nfl_account'
start_date = '2022-11-01'
end_date = '2022-11-30'
provided_for = 'nfl'
account_id = '0000000'
#Run the function with the required parameters:
upload = upload_revshare_data(
endpoint=endpoint,
uploaded_by=uploaded_by,
account_id=account_id,
start_date=start_date,
end_date=end_date,
provided_for=provided_for,
template=template,
reference='API upload NFL 2022 Game Week 16',
token=api_key,
records=json_data
)
Getting the status of an upload
Method: GET
Returns the status of an upload that was done via the request above. Returns rich error information for smaller numbers of errors.
API Endpoints
UAT
https://uat.revshare.api.geniussports.com/api/uploads/{upload_uuid}
Production
https://production.revshare.api.geniussports.com/api/uploads/{upload_uuid}
Mandatory parameters
Parameter | Description | Value type |
|---|
token | Client's Authentication Token | string Example: token=6cfc21c0-7e5b-11ed-a1eb-0242ac121112 |
Path parameters
Parameter | Description | Value type |
|---|
{upload_uuid} | The upload_uuid that is returned by the POST/upload request. (See example responses above) | string <uuid> Example: https://uat.revshare.api.geniussports.com/api/uploads/5xxxxxx3-8xx9-4xx6-8xx4-exxxxxxxxx17 |
Response
The response will return the upload_uuid, upload_ref and status of the upload. Errors will be summarised per error type in the response.
Example response
{
"result":"success",
"data":{
"upload_id":"5xxxxxx3-8xx9-4xx6-8xx4-exxxxxxxxx17",
"upload_ref":"API upload NFL Account '22 Game Week 16 test 6 April",
"upload_valid":true,
"import_status":"partially_validated",
"imported_records":15,
"results":{
"valid_records":14,
"failed_records":1,
"ignored_records":0,
"number_of_errors":2,
"errors":[
{
"code":"BAD_LB_PCT_OF_TS",
"name":"Land-based % of Total Stake is out of range.",
"count":1
},
{
"code":"BAD_OL_PCT_OF_TS",
"name":"Online % of Total Stake is out of range.",
"count":1
}
]
}
}
}
Downloading Usage
Method: GET
Returns a full set of usage data from the Genius Sports systems for the specific customer account. All data is returned in B2B upload format (Brands included).
API Endpoints
UAT
https://uat.revshare.api.geniussports.com/api/account/{account_id}/usage
Production
https://production.revshare.api.geniussports.com/api/account/{account_id}/usage
Mandatory parameters
Parameter | Description | Value type |
|---|
year | The year for the requested usage data | string Example: 2023 |
month | The month for the requested usage data | string Example: 2 |
limit | A limit for the result size. Defaults to 1000. Requesting more than a few thousand rows is not advised as the responses will get slower. | integer Example: 1000 |
token | Client's Authentication Token | string Example: token=6cfc21c0-7e5b-11ed-a1eb-0242ac121112 |
Path parameters
Parameter | Description | Value type |
|---|
{account_id} | The Account ID of the customer | string Example: 121121 |
Response
The API returns a 200 response when the usage data was successfully generated. The usage data is passed as a JSON in the body of the response. A “next” link is returned as part of the response that can be followed for the next page of results if multiple pages or results need to be served.
NB: usage_gameweek is only returned for NFL fixtures.
Example success body
{
"result": "success",
"page": 1,
"next": "/api/account/121121/usage?year=2023&month=1&page=2&limit=1000&token=6cfc21c0-7e5b-11ed-a1eb-0242ac121112",
"data": [
{
"brand_id": 100111,
"brand_name": "BrandName",
"usage_type": "InPlay",
"usage_year": "2023",
"usage_month": "1",
"usage_gameweek": null,
"sport_id": 10,
"sport_name": "Football",
"competition_id": 11968,
"competition_name": "Argentina Torneo Regional Amateur",
"fixture_id": 9943324,
"fixture_name": "Atlético Uruguay v 9 de Julio Rafaela",
"fixture_date": "29-JAN-2023",
"fixture_time": "23:30"
},
{
"brand_id": 100112,
"brand_name": "BrandName2",
"usage_type": "InPlay",
"usage_year": "2023",
"usage_month": "1",
"usage_gameweek": null,
"sport_id": 10,
"sport_name": "Football",
"competition_id": 1547,
"competition_name": "Brazil Pernambucano",
"fixture_id": 9895576,
"fixture_name": "Salgueiro AC v Central SC",
"fixture_date": "28-JAN-2023",
"fixture_time": "23:00"
},
{
"brand_id": 100113,
"brand_name": "BrandName3",
"usage_type": "NFL",
"usage_year": "2023",
"usage_month": "1",
"usage_gameweek": 22,
"sport_id": 17,
"sport_name": "American Football",
"competition_id": 296,
"competition_name": "NFL",
"fixture_id": 9250368,
"fixture_name": "Denver Broncos v Los Angeles Chargers",
"fixture_date": "08-JAN-2023",
"fixture_time": "21:25"
},
{
"..." : "..."
},
]
}