Connecting to Fixtures

Apart from live data that you get from queues over AMQP protocol, Bayes offers Fixtures API. This API provides you with detailed information about the matches, tournaments, teams, players and more.

Fixtures API uses a special kind of identifier, called PERID, for all its entities. It also keeps track of other ID types used in Bayes and external esports ecosystems. If you want to find a connection between Live Data URN, PERID or STEAM ID then Fixtures API is the right place to go.

The data in the Fixtures API is synchronized with Live Data. A common task in Live Data processing is matching the entities from the message to the corresponding Fixtures entities.

Here is an example. This JSON message is sent when a grenade, thrown by a Counter-Strike player, hits the ground:

// note that IDs in this example were intentionally obfuscated and cannot be looked up
{
  "path": "esports/csgo/prodb/esea/esl-challengerleague-s40-ap/8744ac57-789c-530a-c145-e2b3ac154e49",
  "seqIdx": 5111,
  "timeSent": "2022-03-15T12:41:10.107519Z",
  "providerSlug": "bayes",
  "payload": {
    "urn": "live:csgo:prodb:map:8744ac57-789c-530a-c145-e2b3ac154e49",
    "payload": {
      "createdAt": "2022-03-15T12:41:10.094674Z",
      "liveDataMatchUrn": "live:csgo:prodb:map:8744ac57-789c-530a-c145-e2b3ac154e49",
      "sourceUpdatedAt": "2022-03-15T12:41:05.630Z",
      "title": "CSGO",
      "type": "GAME_EVENT",
      "subject": "PLAYER",
      "action": "THREW_ITEM",
      "payload": {
        "gameTime": 10906,
        "timeRemaining": 104094,
        "currentRoundNumber": 20,
        "position": [-1962, 1479, 32],
        "playerUrn": "live:csgo:prodb:player:3424602f-0440-59f0-c6a3-33ed3c657993",
        "teamUrn": "live:csgo:prodb:team:7401ad35-d7ff-5694-0a5a-f05630415451",
        "item": "smokegrenade"
      },
      "additionalProperties": {
        "perId": "esports:match:bd798412-f932-5ec8-0005-3ab77b28c01a",
        "organizer": "ESL",
        "gameNumber": "1",
        "eslRoundId": "8744ac57-789c-530a-c145-e2b3ac154e49",
        "eslTournamentId": "dde62a0e-bb83-581e-9569-f05f141c1b44",
        "eslTournamentName": "ESL Challenger League - 2022 - Season 40 - Asia - Group Stage",
        "eslMatchId": "c564a99d-ff92-57ac-09f2-cb462ea65d48",
        "live:csgo:prodb:team:7401ad35-d7ff-5694-0a5a-f05630415451": "esports:team:3ead3871-fd4c-560c-06b2-04cb51a3c21e",
        "live:csgo:prodb:team:beeec81f-e791-582b-0e67-2147e5b68e43": "esports:team:a4bb8010-51f3-59f4-04ef-64ba9b0d1d90"
      }
    },
    "type": "CSGO_PRODB",
    "version": "0.3",
    "properties": {}
  },
  "references": null,
  "version": "2.0"
}

The highlighted lines contain different types of IDs.

If you store fixtures in your system, you can make use of the ID mapping in the additionalProperties field. The mapping keys that are prefixed with live:csgo:prodb:team:... are Live Data URNs used to identify teams in Live Data. The values, prefixed with esports:team:..., are team PERIDs from Fixtures. Knowing this pair of identifiers, you can make a reliable connection between the team entity in these two systems.

While mapping Live Data URNs to PERIDs is the fastest way to connect Live Data to Fixtures, you can still do it without storing fixtures in your system. The universal method GET /identifiers/lookup allows you to look up entities in Fixtures API using any kind of ID.

Back to our example. After receiving the message, you may want more info about the player who threw the grenade. Take the Live Data URN from the playerUrn field and pass it in the value query parameter to the universal lookup method:

$ curl --request GET \
  --url https://fixtures.bayesesports.com/api/v1/identifiers/lookup?value=live:csgo:prodb:player:3424602f-0440-59f0-c6a3-33ed3c657993 \
  --header 'Authorization: Bearer <your access token>'

The JSON response would be:

{
  "id": 18481532,
  "perid": "esports:player:e55b9299-1fd3-591e-c117-8cce38c2838a",
  "identifiers": [
    {
      "value": "53705599099550735",
      "type": "steam_player_id"
    },
    {
      "value": "live:csgo:prodb:player:3424602f-0440-59f0-c6a3-33ed3c657993",
      "type": "bayes_live_data_urn"
    },
    {
      "value": "928829",
      "type": "sr_player_id"
    },
    {
      "value": "03d87192-98fc-5cae-c4d1-f00bd85f0cf5",
      "type": "esl_player_id"
    }
  ],
  "context": "player",
  "name": "player1",
  "media": {
    "headshot": "https://fixtures.bayesesports.com/static/img/player_default.png"
  }
}

The response contains a full player entity from the Fixtures database. You can see that PERID has its own designated field. The identifiers field holds several IDs associated with this player.

GET /identifiers/lookup is a universal method, so you can use it to search any entity by any type of identifier. For example, you can find a team by teamUrn or a match by perid.

This is not always convenient, because you may have to add additional entity type checks in your processing functions. If you want to make sure the API call will return a specific type of entity, use GET /player/{id}, GET /match/{id} and other related methods. These API calls require you to know an internal entity id.