Make your first World Sports API request
Your first request, the API reference, and everything in between.
From API key to first request.
Set up your account, create a key, fetch your first competitions, then tonight’s GB TV listings. Start here, then explore the endpoints when you’re ready.
Create your account
Open the dashboard and sign in with Google, or create an account with your email and password. If you use email, verify your address before continuing.
Open dashboardCreate and save your API key
In Your API keys, select Create key. Give it a name you’ll recognise, such as
My app · development, then create it.Copy the full key and save it securely—it’s shown only once. You’ll use it as
SPORT_API_KEYin the next step. Keep it in your server environment, outside your source code.Make your first request
Replace
YOUR_API_KEYwith your key in the cURL example. The JavaScript and Python examples readSPORT_API_KEYfrom your server environment. This request lists the football competitions (sport ID 1) in the V2 catalogue.export SPORT_API_BASE_URL="https://worldsportsapi.com/api/v2" export SPORT_API_KEY="YOUR_API_KEY" curl "$SPORT_API_BASE_URL/competitions?sport_ids=1" \ -H "x-api-key: $SPORT_API_KEY"A successful request returns a JSON array of competitions with their
id,name,slug,sport_id,country_idandgender. Look up country names with/countries. An empty array means no competitions matched.A
401means the key is missing, invalid, expired or revoked: check that you copied the full key and sent thex-api-keyheader. A403means the request origin or key scope is not allowed. A429means a limit was reached: readRetry-Afterbefore retrying. See limits and errors for every status.Fetch tonight’s GB TV listings
TV listings cover GB and IE only, and vary by competition. This request returns today’s fixtures that have a known GB TV listing, with times in London time. For Ireland, use
market=IEandtimezone=Europe/Dublin.export SPORT_API_BASE_URL="https://worldsportsapi.com/api/v2" export SPORT_API_KEY="YOUR_API_KEY" TODAY=$(TZ=Europe/London date +%F) curl --get "$SPORT_API_BASE_URL/matches" \ -H "x-api-key: $SPORT_API_KEY" \ --data-urlencode "start_date=$TODAY" \ --data-urlencode "end_date=$TODAY" \ --data-urlencode "timezone=Europe/London" \ --data-urlencode "market=GB" \ --data-urlencode "broadcasts_only=true"Each fixture carries a
broadcastsarray with thechannel,broadcasterandbroadcast_kindof each listing.broadcasts_only=trueleaves out fixtures without a known listing, so an emptyitemsarray means no GB listing is known for that day. Pages hold up to 100 fixtures: whennext_cursoris set, send it ascursorwith the same query. The same401,403and429handling applies. See the global schedule contract for every filter.