Release Notes

September 2021

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

July 2021

What did we improve?

API service: since July 20th 2021 our current version for production usage is v3, v2 remains active as “legacy” version.

What did we fix?

We fixed a bug on API service where fetching players on v3 endpoints did not return imageDataURL

June 2021

Version Switching

On July 20th 2021 we will switch V3 as the Current version. V2 will become Legacy.

Please see https://apidocs.wyscout.com/#section/Versioning for any related detail.


What did we improve?

We published a set of improvements for our V3 endpoints
– coaches/wyid
– players/wyid
– teams/wyid
– teams/wyid/squad

coaches/wyid
The endpoint now also returns assistant coach profiles.
In the output there is a new field: “type” for identifying the role.

coaches/wyid, players/wyid, teams/wyid
They all contain by default a not encoded weblink to the associated image.
This could be very useful for direct integration into third party’s tools.

teams/wyid/squad
there is a new array object called “staff” to include assistant coaches when available.

What did we fix?

We fixed our duel won/lost calculation system for match_events that resulted in unpaired duels, wrong related duel related event information or impossible outcome combinations. Now in case of a duel pair with one of the players that cannot be identified we show the event and use the notation playerId=0.

May 2021

Version Switching

On July 20th 2021 we will switch V3 as the Current version. V2 will become Legacy.

Please see https://apidocs.wyscout.com/#section/Versioning for any related detail.


What did we improve?

  •  We added to our API documentation some details about our versioning system and fixed some unclear field definitions.

What did we fix?

  • We fixed a bug on our duel won/lost calculation system for match_events_v2 that resulted in impossible outcome combinations, give that the allowed outcome should be one of: won/lost, lost/won, neutral/neutral.

April 2021

What did we fix?

  • Fixed a bug on matches/wyid endpoint where a single team’s lineup showed up as being the lineup for both teams.
  • Fixed a bug about some missing stats for youth matches.
  • We fixed a bug on matches/wyid/formations where we had wrong values for the end time of module usage.

March 2021

What did we change?

We made a modification regarding temporary test API endpoints:

  • player/wyid/marketvalue
  • player/wyid/injuries

These endpoints remain reachable and callable on V2 by existing test users with the corresponding capability enabled.

The same endpoints are disabled on V3, they are not part of our standard DB package offer.

What did we fix?

  • We fixed a bug on teams/wyid/advancedstats?compId=x where a wrong error code was returned when using special case values of compId like 0, negative number or type text.
  • We fixed a bug on team/wyid/squad where the user could retrieve empty data of when using the special case value of seasonId=0
  • We fixed a bug on team/wyid/matches where the user could retrieve data of the current season when using the special case value of seasonId=0
  • We fixed a bug on team/wyid/advancedstats where the user could retrieve data of the current season when using the special case value of roundId=0
  • We fixed a bug on team/wyid/advancedstats where the user could retrieve data of the current season when using the special case value of seasonId=0
  • We fixed a bug on match/wyid/formation API endpoint where the optional query parameter fetch=players was not working.
  • We fixed a bug on updatedobjects API endpoint where under particular conditions the system was returning an empty payload
  • Fixed a bug on API endpoint teams/{wyId}/fixtures were the optional parameters fromDate and toDate worked only if both used.
  • We fixed a bug on API endpoint seasons/wyid/players, where the user could wrongly retrieve a list of 23 players using as wyid the special case value of 0.
  • We fixed a bug on v3/matches/wyid/events API endpoint where the “possession_attack_withGoal” flag was sometimes wrong

February 2021

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.

January 2021

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.

December 2020

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)

November 2020

Updated Objects

We added to the “”updated_objects”” API endpoint a new important data type to be retrieved.

The customer can run this call in order to get the list of objects that has changed since a certain date.

Now you can get updates also for match events. The most useful application of this is the possibility to query changes on the match events tables, that is basically a trigger that let the customer know when a match has been analyzed and events and statistical data are ready to be retrieved. This is a big optimization on customer side when they want to keep their data aligned with Wyscout Data, customers can run a more efficient process and query for match data only when they know the match is ready instead of blindly and recursively querying the API service until getting the match data.

Link to documentation: https://apidocs.wyscout.com/#tag/Extra/paths/~1updatedobjects/get

What did we improve?

  • Added a functionality to display the “awarded” matches previously not available in the list of played matches. Now also matches marked as “cancelled”, “postponed” and “suspended” are viewable.

What did we fix?

  • Missing data about spanish competition in the competition list

October 2020

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

July 2020

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",
…..