The only allowable actions on the Marcotti-Summary API are with HTTP GET, OPTIONS, and HEAD verbs.
To access the Marcotti-Summary API, you must include an application ID app_id and key app_key in the request:
https://api-summary.soccermetrics.net/v0/?app_id=f53baabb&app_key=demo1234567890demo1234567890
Warning
This is a fictitious API ID and key. We ask all interested users to request access to the API in order to receive credentials.
Your application ID allows us to track usage of the API to you and your application. Your application key allows the API to prove that you are who you say you are.
To get an application ID/key, go to the Developer Portal at http://soccermetrics.3scale.net. and complete the required information. The organization/group name field can be filled by your name if you are an individual. Your application ID and key will display on the screen. Please make note of them.
Please keep your key secure! We recommend that you use a helper library to access the API.
Warning
Resource URLs in this documentation will not include application IDs and keys for brevity and clarity. When you make a request to the API, you must include authentication credentials every time in the URL.
You can retrieve response header data by making a HEAD request of the resource.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request is successful and response headers are sent to the client. |
| 403 | AUTHENTICATION FAILED | Request failed because of incorrect application ID and/or key. |
| 403 | SSL REQUIRED | Request failed because it was not made over HTTPS. |
| 404 | NOT FOUND | The requested resource cannot be found. |
| 407 | AUTHENTICATION MISSING | Request failed because of missing application ID and/or key. |
| 500 | INTERNAL SERVER ERROR | The resource cannot be delivered because of a server-side error. |
Most of your interaction with the API will involve retrieval of resource representations, or data, to put it another way. To retrieve representations you make a GET request to the resource. This is as simple as copying and pasting a URL into your web browser, but this step can be automated.
You can filter a resource to return those data that satisfy a set of query parameters. These parameters are in almost all cases the field names of the underlying database table.
Query filters are applied after the ? symbol in the URL, and concatenated with the & symbol. Only equality conditions are allowed and exact matches are returned.
Example #1:
Return all players who are from Argentina or eligible to play for Argentina.
GET /v0/personnel/players?country_name=Argentina HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
Example #2:
Return all matches between Liverpool and Arsenal (home team first).
GET /v0/matches/info?home_team_name=Liverpool&away_team_name=Arsenal HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
Note
If a query parameter is repeated in the URL, the last value in the URL request is passed to the database query.
New in version 0.8.
You can sort the order of the resource representations when you make a request to the API. To do so include sort in the query parameter list and add a list of response parameters separated by commas.
Changed in version 0.9.
To sort the parameter in reverse order, place a ‘-‘ in front of the parameter name.
https://api-summary.soccermetrics.net/v0/<resources>?sort=[-]<parameter>,[-]<parameter>
Warning
Sorting is not available for the analytics endpoints of the Soccermetrics API.
Example #1:
Sort match venue representations by seated capacity in descending order.
GET /v0/venues?sort=-seated HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
Example #2:
Now let’s sort match venue representations by latitude from north to south (descending), then longitude from west to east (ascending).
GET /v0/venues?sort=-latitude,longitude HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
New in version 0.9.
You can request a partial representation of the resource by specifying which fields are to be returned by the API. To do so include fields in the query parameter list and add a list of field names separated by commas.
https://api-summary.soccermetrics.net/v0/<resources>?fields=<name-1>,<name-2>,<name-n>
Note
The id field of each record is always returned by the API, regardless of whether it was specified in the fields list.
Warning
Partial representations are not provided for the analytics endpoints of the Soccermetrics API.
Example #1:
Same as Example #1 of the sort resource representation section, but returning city and latitude/longitude data.
GET /v0/venues?sort=-seated&fields=city,latitude,longitude HTTP/1.1
Host: api-summary.soccermetrics.net
Accept: application/json
Example #2:
Retrieve goal timing data of all open play goals scored on a specific matchday.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request is successful and the response body contains the representation requested. |
| 400 | BAD REQUEST | The request was poorly formed and could not processed. For example, you may be trying to retrieve a nonexistent field from a resource. |
| 403 | ACCESS FORBIDDEN | The resource exists, but you can’t access it from the requested URI. This error appears if you attempt to access a base table this is not exposed to the API. It also appears if the application ID and/or key are incorrect. |
| 403 | SSL REQUIRED | Request failed because it was not made over HTTPS. |
| 404 | NOT FOUND | The requested resource cannot be found. |
| 407 | AUTHENTICATION MISSING | Request failed because of missing application ID and/or key. |
| 500 | INTERNAL SERVER ERROR | The resource cannot be delivered because of a server-side error. |
You can access a description of the resource options and payload by making an OPTIONS request to the base resource. A base resource is one without canonical ID numbers, so
/v0/venues
/v0/matches/conditions
are examples of base resources, but
/v0/venues/1014
/v0/matches/1000280/conditions
are not.
Warning
If you make a OPTIONS request to a non-base resource, the response body will be empty.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request is successful and the response body contains the representation requested. |
| 403 | ACCESS FORBIDDEN | The resource exists, but you can’t access it from the requested URI. This error appears if you attempt to access a base table this is not exposed to the API. It also appears if the application ID and/or key are incorrect. |
| 403 | SSL REQUIRED | Request failed because it was not made over HTTPS. |
| 404 | NOT FOUND | The requested resource cannot be found. |
| 407 | AUTHENTICATION MISSING | Request failed because of missing application ID and/or key. |
| 500 | INTERNAL SERVER ERROR | The resource cannot be delivered because of a server-side error. |