Making API Requests¶

The only allowable actions on the Soccermetrics Connect API are with HTTP GET, OPTIONS, and HEAD verbs.

Credentials¶

To access the Soccermetrics Connect API, you must include an application ID app_id and key app_key in the request:

https://api-connect.soccermetrics.net/v1/?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 https://developer.soccermetrics.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.

Retrieving Response Header Data with the HTTP HEAD Method¶

You can retrieve response header data by making a HEAD request of the resource.

Possible HEAD Response Status Codes¶

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.

Retrieving Resources with the HTTP GET Method¶

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.

Filtering On Resource Fields¶

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 – with very few specific exceptions – and exact matches are returned.

Example #1:

Return all players who are from Argentina or eligible to play for Argentina.

GET /v1/personnel/players?country_name=Argentina HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

Example #2:

Return all matches between Liverpool and Arsenal (home team first).

GET /v1/club/matches/info?home_team_name=Liverpool&away_team_name=Arsenal HTTP/1.1
Host: api-connect.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.

Sorting Resource Representations¶

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-connect.soccermetrics.net/v1/<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 /v1/venues?sort=-seated HTTP/1.1
Host: api-connect.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 /v1/venues?sort=-latitude,longitude HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

Partial Resource Representations¶

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-connect.soccermetrics.net/v1/<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 /v1/venues?sort=-seated&fields=city,latitude,longitude HTTP/1.1
Host: api-connect.soccermetrics.net
Accept: application/json

Example #2:

Retrieve goal timing data of all open play goals scored on a specific matchday.

Possible GET Response Status Codes¶

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.

Retrieving Resource Documentation with the HTTP OPTIONS Method¶

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

/v1/venues
/v1/national/matches/conditions

are examples of base resources, but

/v1/venues/ca8200e3ef3049f6bf50ffad05ffe06e
/v1/clubs/matches/9649f4994bf2440b8870d6031815fe65/conditions

are not.

Warning

If you make a OPTIONS request to a non-base resource, the response body will be empty.

Possible OPTIONS Response Status Codes¶

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.