What did we fix?

We fixed a bug on public API endpoint “updated_objects” with “type=matches” where due to some special chars in few team names the payload was not available

We fixed a bug on API endpoint “players/wyid” where inconsistent information were delivered about the player’s current team

What did we improve?

• We added to our Data Glossary and API Documentation websites detailed information about our pitch coordinates system.
• We released a new API endpoint on the v3 “preview” set.
  This new endpoint, matches/wyid/advancedstats/players, allows to retrieve with a single call the advancedstats tables for every player involved in a given match.
  This can lead to a more efficient customer workflows where previously the solution to get the same information was to run a call for each player involved in the match.

What did we improve?

• We released a new API endpoint on the v3 “preview” set.
  This new endpoint, matches/wyid/advancedstats/players, allows to retrieve with a single call the advancedstats tables for every player involved in a given match.
  This can lead to a more efficient customer workflows where previously the solution to get the same information was to run a call for each player involved in the match.

API Versioning

API Versioning system has been delivered.
You can now choose between 3 different sets of API endpoints: legacy, current, preview.
In this moment only the current and preview sets are populated.
We will switch the current version to legacy in around 6 months. Usage of legacy version is deprecated, once a set of API will be pushed out of the legacy version (at least after other 6 months) it will not be available anymore.
This process will continue regularly in order to support new features addiction without disrupting the customer code.
You can refer to our documentation website (https://apidocs.wyscout.com) for details about each version and planned version switches.

Events 3.0

Our new version of match events endpoint is the first new developed endpoint to enter in the new API versioning system.
It has been released in V3.
The new match events endpoint has a modern and richer in content output.

• A new, modern format
• More human readable

It enables two types of workflows to end users:

• Event based analysis
• Possession-based analysis (events are now divided by possession/non-possession)

Some new features include:

• xG for shot and xG post-shot
  If before we used to provide the total amount of expected goals per match, now we provide the xG data for each shot!
  This allows you to find out if a particular single ball possession has been dangerous, just checking if it generated a high xG.
  “Where does our next opponent usually generate danger?”: I can select all the elements with shot: true and xG> 0.5, and create the related chart or even playlist, without wasting time on full matches events.
• Team formation for each single event
  For each event, you have now the output of the related formation of the team.
• Angle and length of each pass
• Timestamp of the Wyscout video for each single event
  It allows you to immediately and intuitively synchronize that event data to the Wyscout video, creating custom playlists or allowing you to visually check the data.
• The file is bigger (more than 1MB), so some items can be excluded!
  The output is fully customizable: if I don’t need the dataset to be human-readable (cause I only need to feed an algorithm, for example), I can exclude the related endpoints from my final output. The result will be a lighter version that allows you to save space.

Download a sample of the new events endpoint here

You can refer to our documentation website (https://apidocs.wyscout.com) for details about endpoint syntax and new content.

What did we improve?

• We are excluding videos/wyid/versions endpoint from the set of available API in V3. This endpoint is no more useful because the same functionality is now available through other video endpoints.
• We are providing a standard pagination system for the season/wyId/players V3 endpoint. Now the user can set the output page size from 1 to 100 using the optional query parameter ‘limit=x’, where the default size is 20. You can refer to our documentation website (https://apidocs.wyscout.com) for details about endpoint syntax.
• We reviewed the output format for V3 videos/wyid/offsets endpoint to align it to the output format of videos/wyid. You can refer to our documentation website (https://apidocs.wyscout.com) for details about the new output format.
• We released a selector to switch between the 3 available versions of our API on the documentation website (https://apidocs.wyscout.com)

Affected API endpoints:

• videos/WYID

New API endpoints:

• videos/WYID/offsets
• videos/WYID/qualities

videos/WYID

example calls:

https://apirest.wyscout.com/v2/videos/5013834
https://apirest.wyscout.com/v2/videos/5013834?start=120&end=250

In the output body of the call you can now find two new objects:

1. “fullhd”
2. “offsets”

1. “fullhd”:
{"url": "xxxx"}

When enabled with an optional commercial package (FullHD option) you can find the link to the FullHD source of the match/clip

2. “offsets”:
{
"1H": {"start": 6,"end": 2711},
"2H": {"start": 2717,"end": 5677},
"E1": {"start": 0,"end": 0},
"E2": {"start": 0,"end": 0},
"P": {"start": 0,"end": 0}
}

The list of offsets values of each time period of the match (First Half, Second Half, Extra time 1, Extra time 2, Penalty shoot out) in respect to the related video file.

In the output headers of the call you can now find three new custom headers:

1. X-RateLimit-TotalSeconds
2. X-RateLimit-RemainingSeconds
3. X-RateLimit-UserReset

These headers refers to the commercial model of minutes of usage per month for accessing API Videos.

X-RateLimit-TotalSeconds = total number of seconds consumed by the user in current billing period (month)

X-RateLimit-RemainingSeconds = total number of seconds remaining in current billing period (month)

X-RateLimit-UserReset = when a new billing period will start and above counters will be reset

Please note: anytime the endpoint is called and the video links are generated the related amount of seconds will be counted, even if the user would not effectively click on the link. Counters are on linking generation, not on effective video usage.

In order not to consume minutes of videos when building videoclips (when you need to know the offset values in advance) or checking for the availability of a certain video quality (lq, sd, hd, fullHd) the customer can use one of the new developed call: videos/wyid/offsets and videos/wyid/qualities.

videos/WYID/offsets

example calls:

https://apirest.wyscout.com/v2/videos/5013834/offsets

Sample output:

{
"matchId": 2852640,
"preMatch": {
"start": 0,
"end": 1
},
"firstHalf": {
"start": 1,
"end": 2881
},
"secondHalf": {
"start": 2882,
"end": 5591
},
"firstHalfExtraTime": null,
"secondHalfExtraTime": null,
"penalties": null
}

You can use this call to understand the offsets of each match period without consuming any minutes in your allowed bucket for video consumption.

videos/WYID/qualities

example calls:

https://apirest.wyscout.com/v2/videos/5013834/qualities

Sample output:

{
"matchId": 5013834,
"lq": {"isAvailable": false},
"sd": {"isAvailable": true},
"hd": {"isAvailable": true},
"fullhd": {"isAvailable": true}
}

You can use this call to check the availability of a specific video quality before building any video request, so without consuming any minutes in your allowed bucket for video consumption

We are modifying the following:

• competitions/wyid/players
• seasons/wyid/players
• player/wyid/advancedstats
• team/wyid/advancedstats
• match/wyid/advancedstats
• player/wyid/matches/matchWyid/advancedstats
• team/wyid/matches/matchWyid/advancedstats
• competitions/wyid/seasons

The competitions and seasons endpoints will have a significant change in their structure.
As for the other endpoints, we added information that will not affect any running scripts or pieces of code.

competitions/wyid/players and seasons/wyid/players

Firstly, we have implemented a pagination system, to solve the problem of endpoints crashing in certain circumstances, especially when the output is large.

Example (same applies to seasons/wyid/players):

https://apirest.wyscout.com/v2/competitions/108/players

Here is the structure of the new output:

"meta": {
"total_items": 1749,
"page_size": 1000,
"page_current": 1,
"page_count": 2,
"availableFilters": {... },
"appliedFilters": {... }
},
"players": [
{ LIST OF PLAYERS }
]

The object “players” is the same as before, but now there is a new “meta” object that contains information about the pagination.

• “total_items”: 1749 – is the total number of players available for this competition
• “page_size”: 1000, – is the current size of the output of each page
• “page_current”: 1, – is the number of the current page (default=1)
• “page_count”: 2, – is the total number of available pages

Therefore, when the total number of players is greater than the page size, you will need to call the following page(s) to access the remaining players, with the following syntax:

https://apirest.wyscout.com/v2/competitions/108/players?page=PAGE_NUMBER

The current page size is set to 1000 as to not substantially affect most competitions, especially at the league level.

There are few exceptions that will have more than 1000 players and these can be addressed using the pagination system.

ATTENTION: The page size is set to 1000 in order to match the current behavior for most competitions.
This size will be reduced in the near future, with a default page size of 20 elements, configurable up to 100 elements per page (using optional parameter &limit=N), so we recommend that you implement the pagination system support on your code or script.

The pages should be easily iterated using the new meta fields described above.

Advanced stats

• player/wyid/advancedstats
• team/wyid/advancedstats
• match/wyid/advancedstats
• player/wyid/matches/matchWyid/advancedstats
• team/wyid/matches/matchWyid/advancedstats

The following variables have been added to the current output of the endpoint while the global structure is not changed.

In player/wyid/advancedstats and player/wyid/matches/matchWyid/advancedstats:
(total and average)

• clearances
• secondAssists, thirdAssists
• shotsBlocked, shotsOnTarget (total)
• fouls, foulsSuffered
• counterpressingRecoveries
• progressivePasses, successfulProgressivePasses (also in percentage)
• slidingTackles, successfulSlidingTackles
• offsides
• goalKicks, successfulGoalKicks, goalKicksShort, goalKicksLong
• dribblesAgainst, dribblesAgainstWon

In team/wyid/advancedstats and team/wyid/matches/matchWyid/advancedstats:

• Offsdes and OpponentOffsides
• ConcededGoals
• ShotsAgainst
• gkGoalKicks, gkGoalKicksSuccess, shortGoalKicks, longGoalKicks

In match/wyid/advancedstats
Possession by quarter (15 minutes) per team, expressed in percentage and minutes of pure possession.
You can refer to https://dataglossary.wyscout.com for a description of each statistical variable.

competitions/wyid/seasons

The following endpoint will now show default details about each listed season, fetching data from the corresponding season/wyid endpoint.

https://apirest.wyscout.com/v2/competitions/28/seasons

Example of output:

{
"competitionId": 28,
"seasons": [
{
"seasonId": "186899",
"season": {
"wyId": 186899,
"name": "2022 Qatar",
"startDate": "2022-11-21",
"endDate": "2022-12-18",
"active": false,
"competitionId": 28
}
},
{
"seasonId": "10078",
"season": {
"wyId": 10078,
"name": "2018 Russia",
…..