The Marcotti-Summary REST API returns only JSON, as do all Soccermetrics APIs.
All responses that do not return an error (HTTP code 200) deliver their payload as follows:
Key | Description |
---|---|
meta | Metadata associated with the resource representation. |
attribution | Attribution objects for the resource representation. |
result | The resource representation itself. |
Note
No metadata are associated with the representation of the service root.
All representations contain a id field, which is their unique ID key.
All string values in the representations are Unicode (UTF-8) representations.
(New in version 0.9.3.) All field names in the representations use camelCase equivalents of the respective database fields. So home_team_name becomes homeTeamName in the response.
Here is a sample JSON representation of high-level match information.
$ curl -i -X GET https://api-summary.soccermetrics.net/v0/matches/1000250/info
Response:
HTTP/1.1 200 OK
Server: gunicorn/0.15.0
Date: Mon, 02 Sep 2013 06:04:37 GMT
Connection: close
Content-Type: application/json
Content-Length: 4342
Access-Control-Allow-Origin: *
{
"meta": {
"totalPages": 1,
"records": 10,
"totalRecords": 1,
"page": 1,
"next": null,
"first": "/v0/matches/1000250/info?records=10&page=1",
"last": "/v0/matches/1000250/info?records=10&page=1",
"prev": null
},
"attribution": {
"html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
"source": {
"html": "<a href=\"http://www.optasports.com\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png\"/></a>"
"logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png",
"url": "http://www.optasports.com",
"name": "Opta Sports"
},
"text": "Powered by Soccermetrics Research",
"url": "http://www.soccermetrics.net",
"logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png"
},
"result": [
{
"firsthalf_length": 45,
"away_manager_name": "Roberto Mancini",
"season_name": "2011-2012",
"competition": 100,
"away_team_name": "Manchester City",
"id": 1000250,
"home_manager": 10017,
"away_team": 10008,
"home_team_name": "Aston Villa",
"venue_name": "Villa Park",
"matchday": 25,
"away_manager": 10014,
"match_date": "2012-02-12",
"referee": 10012,
"home_manager_name": "Alex McLeish",
"season": 100,
"attendance": 35312,
"link": {
"home_manager": "/v0/personnel/managers/10017",
"home_team": "/v0/teams/10001",
"away_team": "/v0/teams/10008",
"stats": {
"setpieces": {
"corners": "/v0/stats/setpieces/corners?match=1000250",
"freekicks": "/v0/stats/setpieces/freekicks?match=1000250",
"throwins": "/v0/stats/setpieces/throwins?match=1000250",
"keyplays": "/v0/stats/setpieces/keyplays?match=1000250"
},
"passes": {
"directions": "/v0/stats/passes/directions?match=1000250",
"lengths": "/v0/stats/passes/lengths?match=1000250",
"locations": "/v0/stats/passes/locations?match=1000250",
"totals": "/v0/stats/passes/totals?match=1000250"
},
"touches": {
"duels": "/v0/stats/touches/duels?match=1000250",
"locations": "/v0/stats/touches/locations?match=1000250",
"totals": "/v0/stats/touches/totals?match=1000250"
},
"crosses": {
"corners": "/v0/stats/crosses/corners?match=1000250",
"totals": "/v0/stats/crosses/totals?match=1000250"
},
"fouls": {
"cards": "/v0/stats/fouls/cards?match=1000250",
"wins": "/v0/stats/fouls/wins?match=1000250"
},
"defense": {
"goalline": "/v0/stats/defense/goalline?match=1000250",
"blocks": "/v0/stats/defense/blocks?match=1000250",
"tackles": "/v0/stats/defense/tackles?match=1000250",
"actions": "/v0/stats/defense/actions?match=1000250",
"clearances": "/v0/stats/defense/clearances?match=1000250"
},
"goals": {
"penalties": "/v0/stats/goals/penalties?match=1000250",
"bodyparts": "/v0/stats/goals/bodyparts?match=1000250",
"locations": "/v0/stats/goals/locations?match=1000250",
"assists": "/v0/stats/goals/assists?match=1000250",
"totals": "/v0/stats/goals/totals?match=1000250"
},
"shots": {
"bodyparts": "/v0/stats/shots/bodyparts?match=1000250",
"plays": "/v0/stats/shots/plays?match=1000250",
"locations": "/v0/stats/shots/locations?match=1000250",
"totals": "/v0/stats/shots/totals?match=1000250"
},
"goalkeeper": {
"actions": "/v0/stats/goalkeeper/actions?match=1000250",
"saves": "/v0/stats/goalkeeper/saves?match=1000250",
"goals": "/v0/stats/goalkeeper/goals?match=1000250",
"shots": "/v0/stats/goalkeeper/shots?match=1000250"
}
},
"referee": "/v0/personnel/referees/10012",
"venue": "/v0/venues/1001",
"away_manager": "/v0/personnel/managers/10014",
"lineups": "/v0/matches/1000250/lineups",
"conditions": "/v0/matches/1000250/conditions",
"events": {
"offenses": "/v0/events/offenses?match=1000250",
"penalties": "/v0/events/penalties?match=1000250",
"goals": "/v0/events/goals?match=1000250",
"substitutions": "/v0/events/substitutions?match=1000250"
}
},
"competition_name": "English Barclays Premier League",
"home_team": 10001,
"kickoff_time": "17:00:00",
"referee_name": "Michael Oliver",
"venue": 1001,
"uri": "/v0/matches/1000250/info",
"secondhalf_length": 47
}
]
}
New in version 0.9.
Whenever you display information obtained from the Soccermetrics API to your users, you must give attribution to Soccermetrics and the source of the data.
Every resource representation from the Soccermetrics API returns an attribution sub-object that contains the following fields:
Property | Description |
---|---|
html | HTML code for attribution to Soccermetrics. |
text | Text of attribution to Soccermetrics. |
logo | URL of “Powered by Soccermetrics” graphic. |
url | URL of Soccermetrics Research web site. |
source | Data source attribution sub-object. |
If your application displays data to users using HTML, you must include the contents of the html field verbatim in a visible place near the data.
If your application does not display data to users with HTML, which is common with native mobile or desktop applications, you must display the text, logo, and a link to the url fields in a visible place near the data. A click on the link should open a browser to the URL.
Warning
Do not modify the contents of the html, text, logo, or url fields.
The source sub-object contains the following fields:
Property | Description |
---|---|
html | HTML code for attribution to data source organization. |
text | Text of attribution to data source organization. |
logo | URL of data source organization logo. |
url | URL of data source organization web site. |
If your application displays data to users using HTML, you must include the contents of the html field verbatim in a visible place near the data.
If your application does not display data to users with HTML, you must display the text field with a link to the url fields in a visible place near the data. A click on the link should open a browser to the URL.
Warning
Do not modify the data in the source sub-object.
No one likes being wrong, but the Marcotti-Summary API returns exceptions in the HTTP response body in case you or the server did something wrong. The exception contains three properties:
Property | Description |
---|---|
status | HTTP status code of the exception. |
message | More descriptive message about the exception. |
uri | The URI of the request the caused the exception. |
Here’s the result of accessing a non-existent resource:
$ curl -i -X GET https://api-summary.soccermetrics.net/v0/matches/100250/assists
Response:
HTTP/1.1 404 NOT FOUND
Server: gunicorn/0.15.0
Date: Sun, 18 Aug 2013 08:26:07 GMT
Connection: close
Content-Type: application/json
Content-Length: 83
{
"status": 404,
"message": "assists resource not found.",
"uri": "/v0/matches/100250/assists"
}
Attempting to access a table not exposed to the API returns the following:
GET /v0/matches HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
Response:
HTTP/1.1 403 FORBIDDEN
Server: gunicorn/0.15.0
Date: Sun, 18 Aug 2013 08:11:53 GMT
Connection: close
Content-Type: application/json
Content-Length: 123
{
"status": 403,
"message": "You do not have access to the matches resource from this URL.",
"uri": "/v0/matches"
}
A major constraint of RESTful APIs is that they must be driven by hypermedia. This concept is encapsulated in the phrase Hypermedia As The Engine of Application State and is further elaborated upon by Dr Roy Fielding on his website. To meet this constraint our REST API includes URI links in representations that help users navigate the API.
All representations except for the service root contain a canonical URI (uri field) that refer to the representation directly. If a resource contains a reference to a subresource, that representation will contain URIs for those subresources in the link field.
For example, a GET request to a Venue resource returns the following response:
GET /v0/venues?city=Sunderland HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
Response:
HTTP/1.1 200 OK
Server: gunicorn/0.15.0
Date: Mon, 19 Aug 2013 04:34:59 GMT
Connection: close
Content-Type: application/json
Content-Length: 446
Access-Control-Allow-Origin: *
{
"meta": {
"records": 10,
"next": null,
"page": 1,
"total_records": 1,
"last": "/v0/venues?page=1&city=Sunderland&records=10",
"total_pages": 1,
"first": "/v0/venues?page=1&city=Sunderland&records=10",
"prev": null
},
"attribution": {
"html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
"source": {
"html": "<a href=\"http://www.optasports.com\"><img src=\"http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png\"/></a>"
"logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/opta_logo.png",
"url": "http://www.optasports.com",
"name": "Opta Sports"
},
"text": "Powered by Soccermetrics Research",
"url": "http://www.soccermetrics.net",
"logo": "http://soccermetrics-mcfc.s3.amazonaws.com/logo/soccermetrics_logo.png"
},
"result": [
{
"city": "Sunderland",
"capacity": 49000,
"name": "Stadium of Light",
"country": 280,
"altitude": 30.0,
"uri": "v0/venues/1014",
"longitude": 54.9144,
"width": 68,
"length": 105,
"link": {
"country": "v0/countries/280"
},
"seated": 49000,
"surface": 1,
"team": 10014,
"latitude": -1.3882,
"id": 1014
}
]
}
Some resources have specialized hypertext to other resource states. A few examples:
There are several other connections between the football data in the API, and we’ll make more connections as they make sense.
New in version 0.8.
The Soccermetrics API contains links and data that describe the number of records returned by a request and permit you to access the response representations in a manageable way.
The pagination data are contained in the meta property of the response representation:
Property | Description |
---|---|
totalPages | Total number of pages in the resource representation. |
totalRecords | Total number of records in resource representation. |
page | Current page number. First page is page 1. |
records | Number of records per page. |
first | The URI of the first page of the representation. |
prev | The URI of the previous page of the representation. |
next | The URI of the next page of the representation. |
last | The URI of the last page of the representation. |
The first and last properties are always populated, but prev and next properties are set to null if no such page exists.
You can control the number of records per page with the records parameter:
Property | Default | Range |
---|---|---|
records | 10 | 1-40 |
For example, you can access all of the penalty kick events in the database, 20 records at a time:
GET /v0/events/penalties?records=20 HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
You can page through the responses using the next parameter. All of the official Soccermetrics API client libraries use this parameter to retrieve successive pages of the response.