Receiving API Responses¶

The Soccermetrics Connect 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 of the ID keys are of type uuid with the exception of the Validation resources listed below, which are of type integer.

Validation Resources
Confederations
Competition Phases
Group Rounds
Knockout Rounds
Weather
Playing Surfaces
Seasons
Time Zones
Name Order
Positions
Fouls
Cards
Body Parts
Shot Events
Penalty Outcomes
Event Actions
Action Modifiers

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-connect.soccermetrics.net/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info

Response:

HTTP/1.1 200 OK
Server: gunicorn/18.0
Date: Fri, 18 Jul 2014 05:47:43 GMT
Connection: close
Content-Type: application/json
Content-Length: 7475
Access-Control-Allow-Origin: *

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {
      "html": "<a href=\"http://www.pressassociation.com\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png\"/></a>",
      "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png",
      "name": "Press Association",
      "url": "http://www.pressassociation.com"
    },
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info?records=10&page=1",
    "last": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info?records=10&page=1",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "attendance": 62103,
      "awayManager": "db04263a62e9468aa3db0d8693d91d1c",
      "awayManagerName": "Niko Kova\u010d",
      "awayTeam": "8a472ca1fac94ee99e0fe28536637946",
      "awayTeamName": "Croatia",
      "competition": "3f062dd43b8c4f4895bdffc3f5c00467",
      "competitionName": "FIFA World Cup",
      "firstextraLength": null,
      "firsthalfLength": 0,
      "group": "A",
      "homeManager": "7e9dc4c848ba442c8b05f30601e2d0b8",
      "homeManagerName": "Luiz Scolari",
      "homeTeam": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "homeTeamName": "Brazil",
      "id": "9649f4994bf2440b8870d6031815fe65",
      "kickoffTime": "17:00:00",
      "link": {
        "analytics": {
          "match": {
            "segments": "/v1/analytics/match/9649f4994bf2440b8870d6031815fe65/segments",
            "state": "/v1/analytics/match/9649f4994bf2440b8870d6031815fe65/state",
            "tsr": "/v1/analytics/match/9649f4994bf2440b8870d6031815fe65/tsr"
          }
        },
        "awayManager": "/v1/personnel/managers/db04263a62e9468aa3db0d8693d91d1c",
        "awayTeam": "/v1/teams/8a472ca1fac94ee99e0fe28536637946",
        "conditions": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/conditions",
        "events": {
          "actions": "/v1/national/events/actions?match=9649f4994bf2440b8870d6031815fe65",
          "all": "/v1/national/events/all?match=9649f4994bf2440b8870d6031815fe65",
          "touches": "/v1/national/events/touches?match=9649f4994bf2440b8870d6031815fe65"
        },
        "goals": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/goals",
        "homeManager": "/v1/personnel/managers/7e9dc4c848ba442c8b05f30601e2d0b8",
        "homeTeam": "/v1/teams/70ce7b6218a24e1d94c21ed8b5cd070c",
        "lineups": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/lineups",
        "offenses": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/offenses",
        "penalties": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/penalties",
        "referee": "/v1/personnel/referees/01928f7214a74408b382ecabcc95c922",
        "stats": {
          "crosses": {
            "corners": "/v1/national/stats/crosses/corners?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/crosses/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "defense": {
            "actions": "/v1/national/stats/defense/actions?match=9649f4994bf2440b8870d6031815fe65",
            "blocks": "/v1/national/stats/defense/blocks?match=9649f4994bf2440b8870d6031815fe65",
            "clearances": "/v1/national/stats/defense/clearances?match=9649f4994bf2440b8870d6031815fe65",
            "goalline": "/v1/national/stats/defense/goalline?match=9649f4994bf2440b8870d6031815fe65",
            "tackles": "/v1/national/stats/defense/tackles?match=9649f4994bf2440b8870d6031815fe65"
          },
          "fouls": {
            "cards": "/v1/national/stats/fouls/cards?match=9649f4994bf2440b8870d6031815fe65",
            "wins": "/v1/national/stats/fouls/wins?match=9649f4994bf2440b8870d6031815fe65"
          },
          "goalkeeper": {
            "actions": "/v1/national/stats/goalkeeper/actions?match=9649f4994bf2440b8870d6031815fe65",
            "goals": "/v1/national/stats/goalkeeper/goals?match=9649f4994bf2440b8870d6031815fe65",
            "saves": "/v1/national/stats/goalkeeper/saves?match=9649f4994bf2440b8870d6031815fe65",
            "shots": "/v1/national/stats/goalkeeper/shots?match=9649f4994bf2440b8870d6031815fe65"
          },
          "goals": {
            "assists": "/v1/national/stats/goals/assists?match=9649f4994bf2440b8870d6031815fe65",
            "bodyparts": "/v1/national/stats/goals/bodyparts?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/goals/locations?match=9649f4994bf2440b8870d6031815fe65",
            "penalties": "/v1/national/stats/goals/penalties?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/goals/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "passes": {
            "directions": "/v1/national/stats/passes/directions?match=9649f4994bf2440b8870d6031815fe65",
            "lengths": "/v1/national/stats/passes/lengths?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/passes/locations?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/passes/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "setpieces": {
            "corners": "/v1/national/stats/setpieces/corners?match=9649f4994bf2440b8870d6031815fe65",
            "freekicks": "/v1/national/stats/setpieces/freekicks?match=9649f4994bf2440b8870d6031815fe65",
            "throwins": "/v1/national/stats/setpieces/throwins?match=9649f4994bf2440b8870d6031815fe65"
          },
          "shots": {
            "bodyparts": "/v1/national/stats/shots/bodyparts?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/shots/locations?match=9649f4994bf2440b8870d6031815fe65",
            "plays": "/v1/national/stats/shots/plays?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/shots/totals?match=9649f4994bf2440b8870d6031815fe65"
          },
          "touches": {
            "duels": "/v1/national/stats/touches/duels?match=9649f4994bf2440b8870d6031815fe65",
            "locations": "/v1/national/stats/touches/locations?match=9649f4994bf2440b8870d6031815fe65",
            "totals": "/v1/national/stats/touches/totals?match=9649f4994bf2440b8870d6031815fe65"
          }
        },
        "substitutions": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/substitutions",
        "venue": "/v1/venues/8a7f4c27f12045638bcba2552747fb8b"
      },
      "matchDate": "2014-06-12",
      "matchday": 1,
      "phase": 2,
      "phaseName": "Group",
      "referee": "01928f7214a74408b382ecabcc95c922",
      "refereeName": "Yuichi Nishimura",
      "round": 1,
      "roundName": "Group Stage",
      "season": 101,
      "seasonName": "2014",
      "secondextraLength": null,
      "secondhalfLength": 0,
      "uri": "/v1/national/matches/9649f4994bf2440b8870d6031815fe65/info",
      "venue": "8a7f4c27f12045638bcba2552747fb8b",
      "venueName": "Arena Corinthians"
    }
  ]
}

Attribution¶

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.

Exceptions¶

No one likes being wrong, but the Soccermetrics Connect 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.

Example 1:¶

Here’s the result of accessing a non-existent resource:

$ curl -i -X GET https://api-connect.soccermetrics.net/v1/clubs/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: 88

{
  "status": 404,
  "message": "assists resource not found.",
  "uri": "/v1/clubs/matches/100250/assists"
}

Example 2:¶

Attempting to access a table not exposed to the API returns the following:

GET /v1/matches HTTP/1.1
Host: api-connect.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": "/v1/matches"
}

Hypermedia References¶

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 /v1/venues?city=Porto+Alegre HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

Response:

HTTP/1.1 200 OK
Server: gunicorn/18.0
Date: Fri, 18 Jul 2014 05:50:41 GMT
Connection: close
Content-Type: application/json
Content-Length: 1589
Access-Control-Allow-Origin: *

{
  "attribution": {
    "html": "<a href=\"http://www.soccermetrics.net\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png\"/></a>",
    "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/soccermetrics_logo.png",
    "source": {
      "html": "<a href=\"http://www.pressassociation.com\"><img src=\"http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png\"/></a>",
      "logo": "http://soccermetrics-connect-v1.s3.amazonaws.com/logo/PressAssociation.png",
      "name": "Press Association",
      "url": "http://www.pressassociation.com"
    },
    "text": "Powered by Soccermetrics Research",
    "url": "http://www.soccermetrics.net"
  },
  "meta": {
    "first": "/v1/venues?city=Porto+Alegre&page=1&records=10",
    "last": "/v1/venues?city=Porto+Alegre&page=1&records=10",
    "next": null,
    "page": 1,
    "prev": null,
    "records": 10,
    "totalPages": 1,
    "totalRecords": 1
  },
  "result": [
    {
      "altitude": 8.0,
      "capacity": 51300,
      "city": "Porto Alegre",
      "country": "70ce7b6218a24e1d94c21ed8b5cd070c",
      "id": "3edfd9ebd9f2485fbb705069ac2f7a05",
      "latitude": -30.065614,
      "length": 105,
      "link": {
        "country": "/v1/countries/70ce7b6218a24e1d94c21ed8b5cd070c"
      },
      "longitude": -51.236086,
      "name": "Est\u00e1dio Beira-Rio",
      "seated": 51300,
      "surface": 1,
      "team": null,
      "timezone": 1058,
      "uri": "/v1/venues/3edfd9ebd9f2485fbb705069ac2f7a05",
      "width": 68
    }
  ]
}

Some resources have specialized hypertext to other resource states. A few examples:

All player resource representations contain hypertext to matches in which they participated and club and national match events in which they were involved.
All match resource representations contain hypertext to their corresponding match events and all statistical records associated with the match.
All country resource representations contain hypertext to representations of match personnel who come from the same country.

There are several other connections between the football data in the API, and we’ll make more connections as they make sense.

Paging Resources¶

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.

Warning

Some of the Validation resources cannot be paginated. Please consult the Validation documentation for more details.

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 /v1/clubs/matches/penalties?records=20 HTTP/1.1
Host: api-connect.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.