The League Matchups script creates a list of match fixtures grouped by matchday. It queries the user for starting and ending matchdays and retrieves match dates, kickoff times, the home/away teams, and venue and referee data for matches within that period.
There’s very little that’s analytical about this example, but it does illustrate how data are retrieved from the API.
Language:
This script is written in Python 2.7 using the official API client for Python. The client simplifies the process of making HTTP requests to the Soccermetrics API and unpacking the responses.
The total length of the script is approximately 20 lines.
Concept
This script calls match.information.get() and match.link.get(), making use of the hypertext provided with the match.information response. We’ll also make use of the sorting functionality so that the response data are in the order we want.
Walkthrough
At the very top of the script we do our imports. Import the sys package (for reasons that will become clear later on) and import the SoccermetricsRestClient package that will allow us to communicate with the API.
import sys
from soccermetrics.rest import SoccermetricsRestClient
In the main routine we create a SoccermetricsRestClient object. You can instantiate it by passing the authentication tokens through the account and api_key variables, but we recommend storing those tokens in environmental variables.
if __name__ == "__main__":
client = SoccermetricsRestClient()
We’re going to get starting and ending matchdays from the command-line arguments (this is why we needed to import the sys module). The user must enter both ranges so we’ll check for that. We’ll also make sure to convert the argument values to integers.
if len(sys.argv) != 3:
sys.stderr.write("Usage: python %s <matchday_start> <matchday_end>\n" % sys.argv[0])
raise SystemExit(1)
matchday_start = int(sys.argv[1])
matchday_end = int(sys.argv[2])
We now iterate between the range of matchdays, and we retrieve match information data from all matches associated with each matchday. (Response data from the API are split into pages, but we can get the full dataset at once with the all() method.) Let’s sort on the match date, and then the kickoff time.
for day in range(matchday_start,matchday_end+1):
matches = client.match.information.get(matchday=day,
sort='match_date,kickoff_time').all()
Finally, we walk through the list of match information data, and we print the data associated with the match. We’ll format the string so that it looks nice. A final newline outside the loop separates the matchdays.
for match in matches:
print "Matchday %02s %s %s %30s v %-30s \t%s (%s)" % (match.matchday,
match.match_date, match.kickoff_time, match.home_team_name,
match.away_team_name, match.venue_name, match.referee_name)
print
Okay, now let’s run it:
$ python examples_matchups.py 2 4
And here’s the result:
Matchday 2 2011-08-20 13:00:00 Sunderland v Newcastle United Stadium of Light (Howard Webb)
Matchday 2 2011-08-20 13:45:00 Arsenal v Liverpool Emirates Stadium (Martin Atkinson)
Matchday 2 2011-08-20 16:00:00 Swansea City v Wigan Athletic Liberty Stadium (Phil Dowd)
Matchday 2 2011-08-20 16:00:00 Everton v Queens Park Rangers Goodison Park (Kevin Friend)
Matchday 2 2011-08-20 16:00:00 Aston Villa v Blackburn Rovers Villa Park (Stuart Attwell)
Matchday 2 2011-08-20 18:30:00 Chelsea v West Bromwich Albion Stamford Bridge (Lee Mason)
Matchday 2 2011-08-21 14:30:00 Norwich City v Stoke City Carrow Road (Neil Swarbrick)
Matchday 2 2011-08-21 15:00:00 Wolverhampton Wanderers v Fulham Molineux Stadium (Mike Dean)
Matchday 2 2011-08-21 17:00:00 Bolton Wanderers v Manchester City Reebok Stadium (Mike Jones)
Matchday 2 2011-08-22 21:00:00 Manchester United v Tottenham Hotspur Old Trafford (Lee Probert)
Matchday 3 2011-08-27 13:05:00 Aston Villa v Wolverhampton Wanderers Villa Park (Martin Atkinson)
Matchday 3 2011-08-27 13:30:00 Wigan Athletic v Queens Park Rangers DW Stadium (Michael Oliver)
Matchday 3 2011-08-27 16:00:00 Chelsea v Norwich City Stamford Bridge (Mike Jones)
Matchday 3 2011-08-27 16:00:00 Blackburn Rovers v Everton Ewood Park (Lee Mason)
Matchday 3 2011-08-27 16:00:00 Swansea City v Sunderland Liberty Stadium (Mark Halsey)
Matchday 3 2011-08-27 18:30:00 Liverpool v Bolton Wanderers Anfield (Lee Probert)
Matchday 3 2011-08-28 14:00:00 Newcastle United v Fulham Sports Direct Arena (Kevin Friend)
Matchday 3 2011-08-28 14:30:00 Tottenham Hotspur v Manchester City White Hart Lane (Phil Dowd)
Matchday 3 2011-08-28 16:00:00 West Bromwich Albion v Stoke City The Hawthorns (Mike Dean)
Matchday 3 2011-08-28 17:00:00 Manchester United v Arsenal Old Trafford (Howard Webb)
Matchday 4 2011-09-10 16:00:00 Everton v Aston Villa Goodison Park (Michael Oliver)
Matchday 4 2011-09-10 16:00:00 Stoke City v Liverpool Britannia Stadium (Mark Clattenburg)
Matchday 4 2011-09-10 16:00:00 Arsenal v Swansea City Emirates Stadium (Stuart Attwell)
Matchday 4 2011-09-10 16:00:00 Wolverhampton Wanderers v Tottenham Hotspur Molineux Stadium (Peter Walton)
Matchday 4 2011-09-10 16:00:00 Manchester City v Wigan Athletic Etihad Stadium (Martin Atkinson)
Matchday 4 2011-09-10 16:00:00 Sunderland v Chelsea Stadium of Light (Lee Probert)
Matchday 4 2011-09-10 18:30:00 Bolton Wanderers v Manchester United Reebok Stadium (Andre Marriner)
Matchday 4 2011-09-11 14:30:00 Norwich City v West Bromwich Albion Carrow Road (Mark Halsey)
Matchday 4 2011-09-11 17:00:00 Fulham v Blackburn Rovers Craven Cottage (Howard Webb)
Matchday 4 2011-09-12 21:00:00 Queens Park Rangers v Newcastle United Loftus Road (Phil Dowd)
Full Script:
#!/usr/bin/env python
import sys
from soccermetrics.rest import SoccermetricsRestClient
if __name__ == "__main__":
client = SoccermetricsRestClient()
if len(sys.argv) != 3:
sys.stderr.write("Usage: python %s <matchday_start> <matchday_end>\n" % sys.argv[0])
raise SystemExit(1)
matchday_start = int(sys.argv[1])
matchday_end = int(sys.argv[2])
for day in range(matchday_start,matchday_end+1):
matches = client.match.information.get(matchday=day,
sort='match_date,kickoff_time').all()
for match in matches:
print "Matchday %02s %s %s %30s v %-30s \t%s (%s)" % (match.matchday,
match.match_date, match.kickoff_time, match.home_team_name,
match.away_team_name, match.venue_name, match.referee_name)
print