Open Football Worldcup Datasource

Simple wrapper API around a set of json files published by openfootball on GitHub:

https://github.com/openfootball

This datasource is for use with the worldcup json files found in this repository:

https://github.com/openfootball/worldcup.json

Usage

npm i @visuallyjs/open-football-worldcup-datasource

import { WorldCupDatasource } from "@visuallyjs/open-football-worldcup-datasource"

// create a datasource
const dataSource = new WorldCupDatasource()

// and ask it things

dataSource.getGroups(2026).then(groups => console.log(g))

React

If you're using it in React you'll probably want to assign to a ref or a memo, eg

import { WorldCupDatasource } from "@visuallyjs/open-football-worldcup-datasource"
import { useMemo, useEffect, useState } from "react"

export default function MyComponent() {
    
    const ds = useMemo(() => new WorldCupDatasource())
    const [groups, setGroups] = useState([])
    
    useEffect(() => {
        ds.getGroups(2026).then(setGroups)
    })  
    
    return <>
        <h1>Groups</h1>
        <ul>{groups.map(group => <li>{group.name}</li>)}</ul>
    </>
}

Methods available

| Method | Return | Description | | :--- | :--- | :--- | | getGroups(year: number) | Promise<Array<Group>> | Gets group definitions for the given year | | getGroup(year: number, name: string) | Promise<Group> | Gets a specific group definition for the given year | | getGroupTeams(year: number, groupName: string) | Promise<Array<Team>> | Gets teams in the given group in the given year | | getTeams(year: number) | Promise<Array<Team>> | Gets all teams in the given year | | getSquads(year: number) | Promise<Array<Squad>> | Gets all squads in the given year | | getSquad(year: number, name: string) | Promise<Squad> | Gets a squad in the given year | | getTeam(year: number, name: string) | Promise<Team> | Gets a team for a given year, by name | | getMatches(year: number) | Promise<Array<Match>> | Gets all matches played in the given year | | getMatch(year: number, matchNumber: number) | Promise<Match> | Gets a match by number, played in the given year | | getStadiums(year: number) | Promise<Array<Stadium>> | Gets all stadiums used as venues in the given year | | getStadium(year: number, name: string) | Promise<Stadium> | Gets a stadium used as a venue in the given year | | getGroupMatches(year: number, groupName: string) | Promise<Array<Match>> | Gets all matches played in the given group in the given year | | getGroupStats(year: number, groupName: string) | Promise<GroupStats> | Collates and returns group info, fully populated team list and matches played in the group | | getFullMatchDetails(year: number, matchNumber: number) | Promise<MatchDetails> | Returns full match details including stadium, teams and squads |

Model

The following interfaces are defined in definitions.ts and represent the data returned by the datasource:

Match

Represents a football match.

• round: The round of the match (e.g., "Round of 16", "Final").
• num: The match number.
• date: The date of the match.
• time: The kickoff time.
• team1: The name of the first team.
• team2: The name of the second team.
• score: The match Score.
• goals1: List of Goals scored by team 1.
• goals2: List of Goals scored by team 2.
• group: The group name, if applicable.
• ground: The stadium or ground name.

Score

Represents the score of a match.

• ft: Full-time score [team1, team2].
• ht: Half-time score [team1, team2].
• et: Extra-time score [team1, team2], if applicable.
• p: Penalty shootout score [team1, team2], if applicable.

Goal

Represents a goal scored during a match.

• name: The name of the player who scored.
• minute: The minute the goal was scored.
• penalty: Whether the goal was a penalty.
• owngoal: Whether the goal was an own goal.

Group

Represents a tournament group.

• name: The name of the group.
• teams: List of team names in the group.

Team

Represents a football team.

• name: The name of the team.
• continent: The continent the team belongs to (Continent).
• fifa_code: FIFA country code.
• flag_icon: URL or path to the flag icon.
• flag_unicode: Unicode representation of the flag.
• group: The group the team is assigned to.
• confed: The confederation the team belongs to.
• id: Unique identifier for the team.
• isoCode: ISO country code.

Stadium

Represents a stadium where matches are played.

• city: The city where the stadium is located.
• name: The name of the stadium.
• capacity: The spectator capacity.
• timezone: The timezone of the stadium's location.
• coords: Geographical coordinates.

Squad

Represents a national squad.

• name: The name of the squad/team.
• fifa_code: FIFA country code.
• players: List of Players in the squad.

Player

Represents a football player.

• name: The name of the player.
• number: The player's jersey number.
• pos: The player's position.
• date_of_birth: The player's date of birth.
• club: Club details ({ name: string, country: string }).

GroupStats

Collated data for a specific group.

• group: Group information.
• teams: List of Teams in the group.
• matches: List of Matches played in the group.

MatchDetails

Full details for a match.

• match: Basic Match data.
• team1: Full Team details for team 1.
• team2: Full Team details for team 2.
• stadium: Stadium details.
• squad1: Squad details for team 1.
• squad2: Squad details for team 2.