Skip to content

Quick start

You need one thing from us: an API key ({API_KEY}). The examples use live; use any product your key includes.

1. Make a request

Every REST call is a GET with your key in the Authorization header:

curl -H "Authorization: Bearer {API_KEY}" "https://api.lineval.com/v1/live/events?limit=5"

The answer is a page of events, without their markets, sorted by start time:

{"data": [{"id": "evt_kdmaf647wxusthff", "product": "live", "name": "Arsenal vs Chelsea", "status": "live"}],
 "nextCursor": null}

(Shortened: every event carries all the fields in Data model; see the complete page example.) Pass nextCursor back as cursor to get the next page; it is null on the last one.

2. Get one event with its markets

curl -H "Authorization: Bearer {API_KEY}" "https://api.lineval.com/v1/live/events/evt_kdmaf647wxusthff"

You get the event with every market and selection: see the live event example. To fetch only part of it, add periods, marketTypes or groups, for example ?groups=player or ?periods=1h,q1.

3. See everything about a game

curl -H "Authorization: Bearer {API_KEY}" "https://api.lineval.com/v1/events/evt_kdmaf647wxusthff"

The game's family says in which of your products the game is offered right now, with a link to each, and where its scoresheet and our verdicts are once there are some (example). Its links are paths: prefix them with https://api.lineval.com.

4. Open the stream

One WebSocket carries every product you list. It starts with a snapshot of each product, then sends only what changes. The stream address is wss://api.lineval.com/v1/stream:

wss://api.lineval.com/v1/stream?products=live,scores

From a server, send the key as a header (the Python client needs websockets 14 or later):

import asyncio, json, websockets

async def main():
    url = "wss://api.lineval.com/v1/stream?products=live,scores"
    async with websockets.connect(url, additional_headers={"Authorization": "Bearer {API_KEY}"}) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            print(msg["type"], msg["product"], msg["seq"])

asyncio.run(main())

In a browser, which cannot set headers on a WebSocket, send the key as the subprotocol:

const ws = new WebSocket("wss://api.lineval.com/v1/stream?products=live,scores", ["{API_KEY}"]);
ws.onmessage = (e) => { const msg = JSON.parse(e.data); console.log(msg.type, msg.product, msg.seq); };

5. Keep your place, and reconnect

Keep, for each product, the since of its snapshot.end and then the seq of every message you apply after it. When the connection drops, reconnect with them and you get only what you missed:

wss://api.lineval.com/v1/stream?products=live,scores&since=live:1795286732015467,scores:1795286731902000

Reconnect after every close except 4400, 4401 and 4403, which need a fix on your side first. Connecting and resuming explains every message, the resume and the back-off.

Complete examples

Two complete clients take every step above, including paging, resuming, back-off and the close codes. They are tested against the API with every change:

  • https://api.lineval.com/docs/examples/quickstart.py: Python 3.10 or later, and pip install websockets.
  • https://api.lineval.com/docs/examples/quickstart.mjs: Node.js 22 or later, no packages. Its stream part runs in a browser as it is.

Set LINES and STREAM at the top to products your key includes, then run either one:

BASE_URL=https://api.lineval.com API_KEY={API_KEY} python quickstart.py 60
BASE_URL=https://api.lineval.com API_KEY={API_KEY} node quickstart.mjs 60

They print what they get and stop after the seconds you give; without them they run until stopped.