DEVELOPER DOCUMENTATION

Make your first World Sports API request

Your first request, the API reference, and everything in between.

Get API key

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.

  1. 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 dashboard
  2. Create 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_KEY in the next step. Keep it in your server environment, outside your source code.

  3. Make your first request

    Replace YOUR_API_KEY with your key in the cURL example. The JavaScript and Python examples read SPORT_API_KEY from your server environment. This request lists the football competitions (sport ID 1) in the V2 catalogue.

    cURL
    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_id and gender. Look up country names with /countries. An empty array means no competitions matched.

    A 401 means the key is missing, invalid, expired or revoked: check that you copied the full key and sent the x-api-key header. A 403 means the request origin or key scope is not allowed. A 429 means a limit was reached: read Retry-After before retrying. See limits and errors for every status.

  4. 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=IE and timezone=Europe/Dublin.

    cURL
    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 broadcasts array with the channel, broadcaster and broadcast_kind of each listing. broadcasts_only=true leaves out fixtures without a known listing, so an empty items array means no GB listing is known for that day. Pages hold up to 100 fixtures: when next_cursor is set, send it as cursor with the same query. The same 401, 403 and 429 handling applies. See the global schedule contract for every filter.