Common Data Models: Overview

Overview models capture the data that describe the details of football competition to which the match belongs.

Contents:

• Competitions
• Countries
• Domestic Competitions
• International Competitions
• Seasons
• Surfaces
• Timezones
• Venue History
• Venues
• Years

Competitions

The Competitions data model contains attributes common to domestic and international competitions.

Attribute	Type	Field Parameters	Description
id	Integer		Unique ID of competition
name	Unicode	60-char limit	Name of competition (not including sponsorship)
level	Integer		Level of competition in league pyramid

Countries

The Countries data model captures data on FIFA-affiliated national associations.

Countries, in football, are defined as FIFA-affiliated national associations. So there are differences between countries that have seats in the United Nations and countries that are represented in FIFA. For example, United Kingdom is not a FIFA country, but England, Scotland, Wales, and Northern Ireland are.

Attribute	Type	Field Parameters	Description
id	Integer		Unique ID of country
name	Unicode	60-char limit	FIFA country
confederation	ConfederationType		FIFA-affiliated confederation of which country is a member

Domestic Competitions

Domestic competitions involve club teams, usually in the same FIFA country, competing against either other.

The DomesticCompetitions data model is inherited from the Competitions model and contains attributes specific to domestic competitions.

Attribute	Type	Description
country_id	Integer	Foreign Key (Competitions): FIFA-affiliated country that governs competition
country	Countries	Reference to country object

International Competitions

International competitions involve either clubs based in different domestic competitions or national teams.

The InternationalCompetitions data model is inherited from the Competitions model and contains attributes specific to international competitions.

Attribute	Type	Description
confederation	ConfederationType	FIFA-affiliated confederation that governs competition

Seasons

The Seasons data model captures the start and end years that make up a football season. These seasons can either fall within a calendar year or span two years.

Attribute	Type	Description
id	Integer	Unique ID of season
start_year_id	Integer	Foreign Key (Years): Start year
end_year_id	Integer	Foreign Key (Years): End year
start_year	Years	Reference to start year object
end_year	Years	Reference to end year object

name()

List the year(s) that make up the season. Seasons within a calendar year will be of form YYYY; seasons over two years will be of form YYYY-YYYY.

This can be used as either a property (which doesn't need the braces), or a query parameter (which does).

reference_date

This property defines the reference date used to calculate player ages.

Season type	Reference date
European (split years)	30 June
Calendar-year	31 December

Playing Surfaces

The Surfaces data model contains data that describes the various types of playing surfaces in match venues.

Attribute	Type	Field Parameters	Description
id	Integer		Unique ID of playing surface
description	Unicode	60-char limit	Descriptive name of playing surface
type	SurfaceType		Type of playing surface

Timezones

The Timezones data model contains data on the timezones within the FIFA confederations. This is used to relate match kickoff times to a common time zone (UTC). Daylight saving time is not taken into account; to do so use the pytz library.

Attribute	Type	Field Parameters	Description
id	Integer		Unique ID of timezone region
name	Unicode	80-char limit	Name of the timezone geographic region
offset	Numeric	-12.00 to +12.00	Offset of time zone region from UTC, in decimal hours
confederation	ConfederationType		FIFA-affiliated confederation in which region lies

Venue History

The VenueHistory data model contains data on the seating and field configurations of a match venue over time.

Attribute	Type	Field Parameters	Description
id	Integer		Unique ID of venue configuration
date	Date		Effective date of venue configuration
length	Integer	90 to 120	Length of venue playing surface in meters (default 105)
width	Integer	45 to 90	Width of venue playing surface in meters (default 68)
capacity	Integer	>= 0	Total venue capacity, seated + unseated (default 0)
seats	Integer	>= 0	Total seats at venue (default 0)
venue_id	Integer		Foreign Key (Venues): Match venue to which configuration relates
venue	Venues		Reference to match venue object
surface_id	Integer		Foreign Key (Surfaces): Playing surface in match venue
surface	Surfaces		Reference to playing surface object

Venues

The Venues data model contains data about match venues.

Attribute	Type	Field Parameters	Description
id	Integer		Unique ID of match venue
name	Unicode	60-char limit	Name of the match venue
city	Unicode	60-char limit	Name of the city/locality where venue resides
region	Unicode	60-char limit	Name of administrative region (state, province, etc.)
latitude	Numeric	-90.000000 to 90.000000	Venue latitude in decimal degrees (default 0.000000)
longitude	Numeric	-180.000000 to 180.000000	Venue longitude in decimal degrees (default 0.000000)
altitude	Integer	-200 to 4500	Venue altitude in meters (default 0)
country_id	Integer		Foreign Key (Countries): Country in which venue resides
country	Countries		Reference to country object
timezone_id	Integer		Foreign Key (Timezones): Timezone in which venue resides
timezone	Timezones		Reference to timezone object

Years

The Years data model contains a list of years.

Attribute	Type	Description
id	Integer	Unique ID of year record
yr	Integer	Year (unique)