Keys and identifiers

Readable keys for what we define, stable ids for what comes and goes.

SockOdds uses two kinds of identifier. Things we define, such as sports, leagues, bookmakers, markets, periods and sides, have readable keys you can type. Things that come and go, such as events and players, have opaque ids that never change once issued.

Readable keys

Keys are lower case letters, digits and underscores, starting with a letter (^[a-z][a-z0-9_]{1,47}$). Examples: sport rugby_league, league rlwc, bookmaker sportsbet, market player_tries_anytime, period half_1, side over. Keys are frozen once published.

Teams have readable keys too, built from the team and its sport, for example australia_rugby_league. Use the key the API returns rather than building one.

Ids

Store ids exactly as returned. An event id stays the same from the first time we list the game to its result; if two listings turn out to be one game, the API answers the surviving id. Market and outcome ids are only meaningful within their event.

Find an event by league and start time with GET /v1/events. If you already hold an official event id, GET /v1/events/lookup finds ours: espn, afl and nrl.

Teams and players

curl -sS "https://api.sockodds.com/v1/teams?league=rlwc&limit=2" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"

const response = await fetch("https://api.sockodds.com/v1/teams?league=rlwc&limit=2", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));

import json, os, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/teams?league=rlwc&limit=2",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
with urllib.request.urlopen(request) as response:
    print(json.dumps(json.load(response), indent=2))

{
  "data": [
    {
      "key": "australia_rugby_league",
      "name": "Australia",
      "sport": "rugby_league",
      "leagues": [
        "rlwc"
      ]
    },
    {
      "key": "new_zealand_rugby_league",
      "name": "New Zealand",
      "sport": "rugby_league",
      "leagues": [
        "rlwc"
      ]
    }
  ],
  "meta": {
    "count": 2,
    "cursor": null
  },
  "links": {
    "next": null
  }
}

curl -sS "https://api.sockodds.com/v1/players?league=rlwc&team=australia_rugby_league&limit=2" \
  -H "Authorization: Bearer $SOCKODDS_API_KEY"

const response = await fetch("https://api.sockodds.com/v1/players?league=rlwc&team=australia_rugby_league&limit=2", {
  headers: { Authorization: `Bearer ${process.env.SOCKODDS_API_KEY}` },
});
console.log(JSON.stringify(await response.json(), null, 2));

import json, os, urllib.request

request = urllib.request.Request(
    "https://api.sockodds.com/v1/players?league=rlwc&team=australia_rugby_league&limit=2",
    headers={"Authorization": "Bearer " + os.environ["SOCKODDS_API_KEY"]},
)
with urllib.request.urlopen(request) as response:
    print(json.dumps(json.load(response), indent=2))

{
  "data": [
    {
      "id": "pl_000ckk0gtfj3",
      "name": "Blayke Brailey",
      "sport": "rugby_league",
      "team": {
        "key": "australia_rugby_league",
        "name": "Australia"
      }
    },
    {
      "id": "pl_000ckk0m9dzm",
      "name": "Bradman Best",
      "sport": "rugby_league",
      "team": {
        "key": "australia_rugby_league",
        "name": "Australia"
      }
    }
  ],
  "meta": {
    "count": 2,
    "cursor": null
  },
  "links": {
    "next": null
  }
}

Sports

Periods

Sides

Regions