Subscription to this function is not available for your account. To upgrade and receive access to this contact sales@datasportsgroup.com
v3 GET /american_football/get_matches
Returns all matches (and related events) that belong to a season, round or match
Request URL
https://dsg-api.com/clients/{client_name}/american_football/get_matches?type=match&id={match_id}&client={client_name}&authkey={client_authkey}
API Threshold
  • 10k calls per hour (2.78 calls per second)
  • This threshold applies to ALL your calls you do across the API.
  • Your number of calls get reset every hour at :00
  • If the thresold is reached within the hour you will get a xml/json message accordingly (which is gone when the next hour starts, see previous point)
Parameters
age
string
unique identifier for an age group
authkey
string Required
client authentification key
client
string Required
unique client ID
detailed
string
only 'yes' is valid to display additional match details
discipline_id
int
unique identifier for a discipline
enddate
string
end date, format 'yyyy-mm-dd' (requires startdate to take effect)
ftype
string
changes feed type from XML to json (ftype=json or ftype=json_array)
gameweek
int
gameweek value to get matches from
gender
string
unique identifier for a gender (male,female)
id
int Required
object id to return
lang
string
two-character language code, defaults to 'en'
picsize
string
one of 200x200, 100x100, 50x50, 30x30 or 18x18 to get correct size of club logo.
startdate
string
start date, format 'yyyy-mm-dd' (requires enddate to take effect)
team_id
int
use a team_id as value to filter the matches accordingly
type
string Required
one of ‘season’, ‘round’ or ‘match’ to which the "id" refers
Nodes
competition❯
details about competition
area_id
unique identifier for an area
area_name
name of the area
competition_id
unique identifier for a competition
format
competition format (domestic_league, domestic_cup, domestic_league_cup, domestic_super_cup, international_cup, international_super_cup, playoff, tournament, race, unofficial)
gender
determines the gender of the competition (male or female)
last_updated
When record was last updated. Format YYYY-MM-DD HH:MM:SS in CET timezone.
name
name of the competition
type
determines if a competition is between club teams (club) or national teams (international)
datasportsgroup❯
details about the API version, sport, language and generation timestamp
generated_utc
UTC timestamp when the API output was generated
lang
language of the API call
sport
sport value
version
version of the API
discipline❯
basic information about the discipline
discipline_id
unique identifier of the discipline
name
name of the discipline
type
type of discipline (contestant, contestant_team or team)
event❯
details about people events
common_name
common name of the person
event_id
unique identifier of a player event
first_name
first name of the person
last_name
last name of the person
membership_id
unique identifier for the membership
minute
game minute when event happened (not display for lineups and subs on bench)
minute_extra
game minute of event after regular time o the period
nationality
nationality of the person
nationality_area_id
unique identifier for an area
people_id
unique identifier for person
period
period type
position
position value
role
type of role ('player', 'coach' or 'assistant_coach', 'goalkeeper_coach', 'local_coach', 'scout', 'sporting director')
second
game second when event happened (not display for lineups and subs on bench)
shirtnumber
shirtnumber value
short_name
shortened name of the person
team_id
unique identifier of the team
team_name
current team name
type
type of event (depends on the parent node)
event_extra❯
extra details about the american football event
yards
distance in yards
gender❯
details about the gender
age_group
defines the age group (senior,u23,u22,u21....)
value
gender type (male, female or mixed)
list❯
details about list type
aggregation_type
aggregation type (scores or wins)
id
unique identifier for a group if type = group, if type = playoff then for a playoff
last_updated
When record was last updated. Format YYYY-MM-DD HH:MM:SS in CET timezone.
name
name of either a group or playoff
score_a
playoff score of team_a
score_b
playoff score of team_b
type
list type (regular, group or playoff)
winner_team_id
unique identifier for the winning team of the playoff
live❯
details about live informations (american football)
clock
time on the clock when the event happened (aka how much time was left till the round ends)
down
current down for the team in possession
period
current period
red_zone
indicator if possession team is in the red zone (value = 1)
to_go
indicates how much yards are to go for the possession team
match❯
details about the match
date
date of match, format 'yyyy-mm-dd' (CET)
date_utc
date of match, format 'yyyy-mm-dd' (UTC)
final_period
display the period in which the match finished.
last_updated
When record was last updated. Format YYYY-MM-DD HH:MM:SS in CET timezone.
match_id
unique identifier of match
score_a
full-time score of team_a
score_b
full-time score of team_b
status
status of the game (Played, Playing, Fixture, Cancelled, Postponed, Suspended, Awarded, Break, Retired, Bye, No Contest, Disqualified, Tech Knockout, Knockout, Draw, Submission) + (Cricket-specific = No Result, Tea, Lunch, Dinner, between Innings, Stumps, rain delay, bad light, crowd trouble, pitch condition, start delay, drinks, super over, floodlight failure)
team_a_area_code
three-letter-acronym of the area where the home team origins
team_a_area_id
unique area_id for team_a
team_a_area_name
area name of home team origins county
team_a_id
unique team ID for team_a
team_a_logo
team logo URL
team_a_name
current name of team_a
team_a_original_name
the real name at the particular season (so can differ to current name)
team_a_short_name
short name of the home team
team_a_tla_name
three-letter-acronym of team_a
team_b_area_code
three-letter-acronym of the area where the home team origins
team_b_area_id
unique area_id for team_b
team_b_area_name
area name of away team origins county
team_b_id
unique team ID for team_b
team_b_logo
team logo URL
team_b_name
current name of team_b
team_b_original_name
the real name at the particular season (so can differ to current name)
team_b_short_name
short name of team_b
team_b_tla_name
three-letter-acronym of team_b
time
start time (CET), format 'hh:mm:ss'.
time_utc
start time (UTC), format 'hh:mm:ss'
venue_type
determines if the match is on neutral ground or on home/away basis (home_away or neutral)
winner
determines the winner of match ('team_A','team_B','draw','yet unknown')
match_extra❯
extra informations about the match
attendance
amount of people that attended the particular match
gameweek
contains the gameweek a match belongs to.
method❯
details about the API function
method_id
unique ID of method
name
name of method
people❯
details and stats of the american football player
assisted_tackles
number of assisted tackles
average_punt_length
average punt length (in yards)
common_name
common name of the person
conversion_pass
number of conversion passes
conversion_pass_attempts
number of conversion pass attempts
conversion_rec_attempts
number of conversion receiving attempts
conversion_rec_made
number of conversion receiving made
conversion_rush_attempts
number of conversion rush attempts
conversion_rush_made
number of conversion rush made
extra_points_blocked
number of extra points blocked
extra_points_made
number of extra points made
extra_points_missed
number of extra points missed
extra_point_attempts
number of extra points attempted
field_goals_made
number of field goals made
field_goal_attempts
number of field goal attempts
first_name
first name of the person
forced_fumbles
number of forced fumbles
interceptions_thrown
number of interceptions thrown
last_name
last name of the person
longest_field_goal
longest ield goal (in yards)
longest_punt
longest punt (in yards)
longest_receiving_touchdown
longest receiving touchdown (in yards)
longest_reception
longest reception (in yards)
longest_rush
longest rush made (in yards)
longest_touchdown_return
longest touchdown returne (in yards)
membership_id
unique identifier for the membership
nationality
nationality of the person
passing_touchdown
number of touchdown passes
people_id
unique identifier for person
position
position value
punt_inside_20
number of punts inside 20
punt_yards
number of punt yards
receiving_targets
number of receiving targets
receiving_touchdown
number of receiving touchdowns
rushing_attempts
number of rushing attempts
rushing_touchdown
number of rushing touchdowns
sacks_made
number of sacks made
shirtnumber
shirtnumber value
short_name
shortened name of the person
team_id
unique identifier of the team
team_name
current team name
total_extra_points
number of total extra points
total_field_goal_points
number of total field goal points
total_interceptions
number of total interceptions
total_passing_yards
number of total passing yards
total_pass_attempts
number of total pass attempts
total_pass_completions
number of total pass completions
total_punts
number of total punts
total_receiving_yards
number of total receiving yards
total_receptions
number of total receptions
total_rushing_yards
number of total rushing yards
total_tackles
number of total tackles
period❯
details about periods of the match
score_a
period score of team_a
score_b
period score of team_b
type
three-letter-acronym of the period
referee❯
details about a specific referee
common_name
common name of the person
first_name
first name of the person
last_name
last name of the person
nationality_area_code
three character area code
nationality_area_id
unique identifier for an area
nationality_area_name
area name of peoples nationality
people_id
unique identifier for person
role
role of the referee
short_name
shortened name of the person
round❯
details about the round
end_date
end date, format 'yyyy-mm-dd'
end_date_utc
end date in UTC timezone, format 'yyyy-mm-dd'
end_time
end time, format 'HH:mm:ss'
end_time_utc
end time in UTC timezone, format 'HH:mm:ss'
last_updated
When record was last updated. Format YYYY-MM-DD HH:MM:SS in CET timezone.
name
name of round
round_id
unique identifier of round
start_date
start date, format 'yyyy-mm-dd'
start_date_utc
start date in UTC timezone, format 'yyyy-mm-dd'.
start_time
start time, format 'HH:mm:ss'
start_time_utc
start time in UTC timezone, format 'HH:mm:ss'
type
determines if the round contains a table or a cup structure (knock-out)
round_extra❯
extra round information
current_gameweek
displays the gameweek of nearest match to today
medal_round
indicates if medals are awarded in this round
status
status of the round (Scheduled,Live,Played,Postponed,Cancelled,Break)
total_gameweek
displays the total of gameweeks for this round
season❯
details about the season
end_date
end date, format 'yyyy-mm-dd'
last_updated
When record was last updated. Format YYYY-MM-DD HH:MM:SS in CET timezone.
logo
full path URL of logo for particular season
original_name
competition name during this season
season_id
unique identifier for season
start_date
start date, format 'yyyy-mm-dd'
title
title of season
tour❯
details about the tour
gender
gender of the tour
name
name of the particular tour
tour_id
unique tour identifier
tour_type
defines if the tournament is part of a tour or not. If not then value "non-tour"
tour_season❯
details about a tour season
logo
full path URL of logo for particular tour_season
name
name of the tour_season
title
title of the particular tour season
tour_season_id
unique identifier of a tour season
venue❯
basic details about the venue
venue_area_id
unique identifier for an area
venue_area_name
name of the area
venue_city
city where the venue is based
venue_id
unique identifier of the venue
venue_image
full path URL of venue or circuit image
venue_name
current name of the venue
weather❯
details about weather
humidity
humidity in %
pressure
pressure in mmHg
temperature
temperature in °C
weather_description
short description of the weather
wind_direction
description of wind direction
wind_speed
value of wind speed
Response Headers
200
Success
401
Unauthorized
429
Too Many Requests
Code Samples
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://dsg-api.com/clients/{client_name}/american_football/get_matches?type=match&id={match_id}&client={client_name}&authkey={client_authkey}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "{User}:{Password}");
$content = curl_exec($ch);
curl_close($ch);
?>
curl GET -u "User:Password" "https://dsg-api.com/clients/{client_name}/american_football/get_matches?type=match&id={match_id}&client={client_name}&authkey={client_authkey}"
Imports System
Imports System.Net	
Imports System.IO
Imports System.Text

Public Module Module1
	Public Sub Main()
		Dim url As String = "https://dsg-api.com/clients/{client_name}/american_football/get_matches?type=match&id={match_id}&client={client_name}&authkey={client_authkey}"
		Dim myReq As WebRequest = WebRequest.Create(url)
		myReq.Credentials = new System.Net.NetworkCredential("{User}", "{Password}")
		Dim wr As WebResponse = myReq.GetResponse()
		Dim receiveStream As Stream = wr.GetResponseStream()
		Dim reader As StreamReader = New StreamReader(receiveStream, Encoding.UTF8)
		Dim content As String = reader.ReadToEnd()
	End Sub
End Module
response = requests.get("https://dsg-api.com/clients/{client_name}/american_football/get_matches?type=match&id={match_id}&client={client_name}&authkey={client_authkey}", auth=("User", "Password"))
Response Example
200 Success
{"datasportsgroup":{"version":"2.73.3","sport":"american_football","lang":"en","generated_utc":"2025-08-01T15:04:17+00:00","method":{"method_id":"73","name":"get_matches"},"tour":{"tour_id":"","name":"","gender":"male","tour_type":"non-tour","tour_season":{"tour_season_id":"","title":"","name":"","logo":"","competition":{"competition_id":"1","name":"NFL","area_id":"203","area_name":"United States","gender":"male","type":"club","format":"domestic_league","last_updated":"2021-07-09 11:17:55","season":{"season_id":"75876","title":"2025\/2026","start_date":"2025-09-04","end_date":"2026-02-09","original_name":"NFL","logo":"https:\/\/www.dsg-images.com\/comps\/200x200\/1.png","last_updated":"2025-05-06 10:14:15","discipline":{"discipline_id":"246","name":"American Football","type":"team","gender":{"value":"male","age_group":"senior","round":{"round_id":"123906","name":"Regular Season","start_date":"2025-09-04","start_time":"","start_date_utc":"2025-09-04","start_time_utc":"","end_date":"2026-01-05","end_time":"","end_date_utc":"2026-01-05","end_time_utc":"","type":"table","last_updated":"2025-05-15 10:23:55","round_extra":{"current_gameweek":"1","total_gameweek":"18"},"list":{"type":"regular","id":"","name":"","match":{"match_id":"3715930","date":"2025-09-05","time":"02:20:00","date_utc":"2025-09-05","time_utc":"00:20:00","team_a_id":"17","team_a_name":"Philadelphia Eagles","team_a_short_name":"Eagles","team_a_tla_name":"PHI","team_a_original_name":"Philadelphia Eagles","team_a_area_id":"203","team_a_area_code":"USA","team_a_area_name":"United States","team_a_logo":"https:\/\/www.dsg-images.com\/sport_entity\/200x200\/674.png","team_b_id":"20","team_b_name":"Dallas Cowboys","team_b_short_name":"Cowboys","team_b_tla_name":"DAL","team_b_original_name":"Dallas Cowboys","team_b_area_id":"203","team_b_area_code":"USA","team_b_area_name":"United States","team_b_logo":"https:\/\/www.dsg-images.com\/sport_entity\/200x200\/677.png","status":"Fixture","winner":"yet unknown","score_a":"","score_b":"","venue_type":"home_away","final_period":"amf_p4s","last_updated":"2025-06-02 20:14:46","period_scores":[],"broadcasters":[],"match_extra":{"gameweek":"1","attendance":"","venue":{"venue_id":"2436","venue_name":"Lincoln Financial Field","venue_city":"Philadelphia, PA","venue_area_id":"203","venue_area_name":"United States","venue_city_id":"120","venue_city_state":"","venue_city_state_abbreviation":""},"weather":{"temperature":"","weather_description":"","wind_speed":"","wind_direction":"","humidity":"","pressure":""}},"live":{"period":"","clock":"","down":"","red_zone":"","to_go":""},"referees":[],"events":{"lineups":[],"subs_on_bench":[],"scores":[]},"team_stats":[],"player_stats":[]}}}}}}}}}}}