League MatchupsΒΆ

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