API service

The API service is based on the REST architecture and supports a number of resources accessed with HTTP protocol. The client should send an HTTP GET request and in return will receive a return list document in JSON format. API support multiple simultaneous requests from authenticated customers. 
We have standardized the output for ALL sports, so we offer the same format and data structure. However, for each sports, there are different event details, incidents, and statistics that are explained in more detail in the Sports data structure section.

Please note that new event details, incidents, and statistics could be added in the future. Whenever new features are added to the API you will find a description in the API change log.

Authentication

Access to the API is based on the oAuth 2.0 authorization method. This means access is given using a unique token without any IP's restriction.

The client is authenticated using a GET request including query string parameters: client_id and secret_key. These parameters are assigned to you by our sales department. On confirmation of the client_id/secret_key combination, the special oAuth token is then returned. The maximum period of time the token is valid is 24 hours from the time it was generated. This token should be sent with all subsequent requests. 

Example token request: 
https://api.statscore.com/v2/oauth?client_id=<YOUR_CLIENT_ID>&secret_key=<YOUR_SECRET_KEY>

Retrieving data

For access to the feed it is necessary to send a URL request containing the following segments:
Base URL: https://api.statscore.com/<api_version>/<resource_name>?token=<YOUR_TOKEN>

In the event you would like additional filtering of the data, you can request a combination of the resource query parameters. For example, the following URL returns all events for basketball (sport_id=1): https://api.statscore.com/<api_version>/events?token=<YOUR_TOKEN>&sport_id=1. The possible parameters for all resources are described in the detailed specifications.

Feed structure

All responses to a successful request (HTTP status code = 200) have the same structure:

"api": {
	"ver": "2.146.0",
	"timestamp": 1575991564,
	"method": {
		"parameters": {
			"client_id": 1,
			"events_details": "yes"
		},
		"name": "events.index",
		"details": "events.index",
		"total_items": 511,
		"previous_page": "",
		"next_page": "https://api.statscore.com/v2/events?token=YOUR_TOKEN&client_id=1&page=2"
	},
	"data": {
	...
	}
}

Element "api" is heading element for each response. The "api" element includes attributes:

• version - means the version in which the data is processed. You should always use the proper version in your code. You can switch the version in the URL request. For more information about versions please see our API changelog.
  

• timestamp - UNIX TIMESTAMP value from API server. This value is generated on every request.

The "data" element contains all requested information.

For each request the HTTP Status code is also returned with a response. A list of all possible HTTP status codes:

Unsuccessful requests/ errors

For unsuccessful requests the response contains <error> element:

"api": {
	"ver": "2.146.0",
	"timestamp": 1575991564,
	"method": {
		"parameters": {
			"client_id": 1,
			"events_details": "yes"
		},
		"name": "events.index",
		"details": "events.index",
		"total_items": 511,
		"previous_page": "",
		"next_page": "https://api.statscore.com/v2/events?token=YOUR_TOKEN&client_id=1&page=2"
	},
	"error": {
		"message": "Invalid credentials. Either the username, password or token you provided is incorrect",
		"status": 401,
		"internal_code": 2
	}
}

Here is a general explanation of possible error codes:

Using timestamp

When any request is made, the response contains a timestamp value showing the time of the last generated response.
If you want to receive feed updates rather than refresh the whole feed then you can store this value and use it in your next request. In the documentation of each resource, we have included cache times. The cache times need to be considered when calling particular requests.

For example: Suppose you refreshed all your data and got the following header in the response:

"api": {
	"ver": "2.146.0",
	"timestamp": 1425992728,
	"method": {
		"parameters": {
			"client_id": 1,
			"events_details": "yes"
		},
		"name": "events.index",
		"details": "events.index",
		"total_items": 511,
		"previous_page": "",
		"next_page": "https://api.statscore.com/v2/events?token=YOUR_TOKEN&client_id=1&page=2"
	},
	"data": {
	...
	}
}

The next request should be as follows:

https://api.statscore.com/<api_version>/<resource_name>/[identifier]?token=<your_token>&timestamp=1425992728

Languages

The default feed language is English. If you would like to get the feed translated you can add as a query parameter (lang) to your request e.g. https://api.statscore.com/v2/areas&lang=pl returns the areas in the Polish language. The list of more popular languages are listed below, or you can get the list of all languages available using: https://api.statscore.com/v2/languages 

Please note that all dates and times are always displayed in the UTC format. This also applies to the timestamps available at the top of the feed structure. All dates used in our services use the ISO 8601 date and time format. For some resources, you can use the query parameter "tz" which determines the timezone for the output data. The list of available time zones is listed below.

Time, date & timezones

Example: https://api.statscore.com/v2/events?token=<YOUR_TOKEN>&tz=Europe/Warsaw