Introducing the Analytics module for Soccermetrics API


It’s been several months since we last posted updates on the Soccermetrics API to the blog.  Not to say that there haven’t been updates — quite a lot, in fact — it’s just that we’ve chosen to reveal those changes through the API documentation pages.  But we’ve introduced a pair of changes that are quite significant, and we’ll reveal them here.

The first major feature is the start of an Analytics module to the Soccermetrics API.  The idea behind the Analytics module is to provide access to derived metrics and structured data that enable more involved analyses, in particular those metrics and data that are a little too complicated to calculate with separate API calls.  We start with two resources: a Match State metric that returns the scoreline at a specific time of the match, and a Match Segment metric that returns the periods of play in which the players on the pitch are unchanged as well as the players involved in each period.  Match states have gained wider use in football analytics, while match segments can be used in conjunction with the Players resource to develop adjusted plus/minus models.

The second major feature is the introduction of partial resource requests.  Typically when you make a request to the Soccermetrics API you receive the full representation of that resource, and our representations can be very detailed.  Many times, you may be interested in only one or two parameters.  To address this pattern we’ve made changes to our backend so that you can specify which fields are to be returned by the API.  Just include the variable fields in the query parameter list and add a list of field names separated by commas.  It’s a feature that we think will not just reduce network bandwidth but also improve usage of the API.

The third major feature is a revised sorting convention.  Previously to sort a response, you added the variable sort to the query parameter list and set it equal to a string of field names and the codes asc or desc to designate the order.  That was a little too verbose, so we changed the convention.  Now when you submit a list of field names to sort the response, just add a minus sign (‘-‘) to designate a sort on that variable in reverse order.  Otherwise we’ll assume that you want a sort in ascending order.  (Note: This feature isn’t working the way we expect, and we hope to have fixed it by the end of the weekend.)

There were some other behind-the-scenes changes to the API, such as improved error handling, more comprehensive logging of API calls, and compression of all API responses.  They will allow us to better monitor API usage, diagnose problems as they occur, and improve the user experience.

We’ll reflect all of these changes in an updated documentation and Soccermetrics API client by the end of the weekend.  The developer’s portal, available to those with credentials to the API, is located here.  And if you have no idea what I’m talking about, you can email [email protected] and enquire about an authentication credential.