# 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

| Identifies | Format | Example shape |
| --- | --- | --- |
| Event | `ev_` then 12 lower case letters and digits | `ev_xxxxxxxxxxxx` |
| Player | `pl_` then 12 lower case letters and digits | `pl_xxxxxxxxxxxx` |
| Market, within an event | `mk_` then 16 lower case letters and digits | `mk_xxxxxxxxxxxxxxxx` |
| Outcome, within a market | `oc_` then 16 lower case letters and digits | `oc_xxxxxxxxxxxxxxxx` |

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

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

```javascript
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));
```

```python
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))
```

Response (from a local copy of the API with invented test prices):

```json
{
  "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
  }
}
```

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

```javascript
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));
```

```python
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))
```

Response (from a local copy of the API with invented test prices):

```json
{
  "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

| Key | Name | Participants |
| --- | --- | --- |
| `australian_football` | Australian football | `home`, `away` |
| `rugby_league` | Rugby league | `home`, `away` |
| `rugby_union` | Rugby union | `home`, `away` |
| `soccer` | Soccer | `home`, `away` |
| `basketball` | Basketball | `home`, `away` |
| `american_football` | American football | `home`, `away` |
| `baseball` | Baseball | `home`, `away` |
| `ice_hockey` | Ice hockey | `home`, `away` |
| `tennis` | Tennis | `competitor_1`, `competitor_2` |
| `mma` | Mixed martial arts | `competitor_1`, `competitor_2` |
| `cricket` | Cricket | `home`, `away` |
| `motorsport` | Motorsport | `competitor_1`, `competitor_2` |
| `esports` | Esports | `home`, `away` |

## Periods

| Key | Name |
| --- | --- |
| `full` | Full match |
| `regulation` | Regulation time |
| `half_1` | First half |
| `half_2` | Second half |
| `quarter_1` | First quarter |
| `quarter_2` | Second quarter |
| `quarter_3` | Third quarter |
| `quarter_4` | Fourth quarter |
| `period_1` | First period |
| `period_2` | Second period |
| `period_3` | Third period |
| `innings_1_to_5` | First five innings |
| `set_1` | First set |
| `set_2` | Second set |
| `set_3` | Third set |
| `set_4` | Fourth set |
| `set_5` | Fifth set |
| `map_1` | Map 1 |
| `map_2` | Map 2 |
| `map_3` | Map 3 |
| `map_4` | Map 4 |
| `map_5` | Map 5 |
| `round_1` | Round 1 |
| `round_2` | Round 2 |
| `round_3` | Round 3 |
| `round_4` | Round 4 |
| `round_5` | Round 5 |

## Sides

| Key | Name |
| --- | --- |
| `home` | Home |
| `away` | Away |
| `competitor_1` | Competitor 1 |
| `competitor_2` | Competitor 2 |
| `draw` | Draw |
| `over` | Over |
| `under` | Under |
| `yes` | Yes |
| `no` | No |
| `odd` | Odd |
| `even` | Even |
| `home_or_draw` | Home or draw |
| `away_or_draw` | Away or draw |
| `either_team` | Either team |

## Regions

| Key | Name |
| --- | --- |
| `au` | Australia |
| `nz` | New Zealand |
| `us` | United States |
| `ca` | Canada |
| `uk` | United Kingdom |
| `ie` | Ireland |
| `eu` | Europe |
| `intl` | International |