football-docs 0.6.2 → 0.6.3

package/README.md

@@ -4,7 +4,7 @@ Searchable football data provider and tooling documentation for AI coding agents
 
 **Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot) to work with football data. Works with any tool that supports MCP.
 
-**What it does:** Gives your AI agent a searchable index of documentation for 19 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, Sportradar, TheSportsDB, FMDB Pro, TransferRoom, and more), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, and more). Your agent looks up the real docs instead of guessing from training data.
+**What it does:** Gives your AI agent a searchable index of documentation for 20 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, Sportradar, TheSportsDB, FMDB Pro, TransferRoom, and more), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, floodlight, and more). Your agent looks up the real docs instead of guessing from training data.
 
 **Why not just let the AI figure it out?** LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.
 
@@ -111,6 +111,7 @@ Provider filters use the indexed provider keys shown by `list_providers`, but co
 | StatsBomb | 237 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-lineups, xg-model, iq-metrics, player/team stats, player-mapping, identity-surfaces |
 | Wyscout | 164 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-analysis-metrics, glossary, identity-surfaces |
 | kloppy | 126 | data-model, usage, provider-mapping, tracking-rendering, event-derived-metrics |
+| floodlight | 145 | core data objects, io parsers (Tracab, DFL, Kinexon, Opta, SkillCorner, StatsBomb, StatsPerform, Second Spectrum), transforms, metrics, models, visualisation, guides |
 | SportMonks | 85 | event-types, data-model, api-access, charting-season-stories, identity-surfaces |
 | databallpy | 63 | data-model, overview, usage |
 | mplsoccer | 64 | overview, pitch-types, visualizations |
@@ -128,7 +129,7 @@ Provider filters use the indexed provider keys shown by `list_providers`, but co
 | Soccerdonna | 7 | identity-surfaces |
 | Transfermarkt | 8 | identity-surfaces |
 
-**1,201 searchable chunks** across 19 providers and tools.
+**1,346 searchable chunks** across 20 providers and tools.
 
 ## Contributing
 

package/dist/crawl.js

@@ -30,6 +30,58 @@ const turndown = new TurndownService({
     codeBlockStyle: "fenced",
     bulletListMarker: "-",
 });
+// Sphinx (and other Pygments-based renderers) mark up code blocks as bare
+// <pre> containing syntax-highlighting <span>s, not <pre><code>. Turndown's
+// built-in fenced-code rule only matches <pre><code>, so these fall through
+// to plain-text handling where markdown-escaping mangles identifiers (e.g.
+// `read_position_data_json` becomes `read\_position\_data\_json`). Read
+// textContent directly to bypass that escaping.
+turndown.addRule("preBlock", {
+    filter: "pre",
+    replacement: (_content, node) => {
+        const code = node.textContent?.replace(/\n+$/, "") ?? "";
+        if (!code.trim())
+            return "";
+        const parentClass = node.parentElement?.getAttribute?.("class") ?? "";
+        const langMatch = parentClass.match(/highlight-(\w+)/);
+        const lang = langMatch && langMatch[1] !== "default" ? langMatch[1] : "";
+        return `\n\n\`\`\`${lang}\n${code}\n\`\`\`\n\n`;
+    },
+});
+// Sphinx marks up identifiers/parameter names/default values in signatures
+// with <span class="pre"> (a "don't word-wrap" hint, not semantic <code>).
+// Same escaping problem as above — render as inline code instead.
+turndown.addRule("sphinxPreSpan", {
+    filter: (node) => node.nodeName === "SPAN" &&
+        (node.getAttribute?.("class") ?? "")
+            .split(/\s+/)
+            .includes("pre"),
+    replacement: (_content, node) => `\`${node.textContent ?? ""}\``,
+});
+// Turndown escapes every underscore in plain text nodes by default (guarding
+// against accidental markdown emphasis), including identifiers that carry no
+// code markup at all — e.g. Sphinx renders parameter/return names in
+// "Variables:" lists as plain `<strong>essential_missing</strong>`, no <code>
+// or .pre span in sight. Since this corpus exists for full-text search rather
+// than pixel-perfect rendering, an escaped underscore that breaks substring
+// matches on the real identifier is worse than the rare accidental italics.
+const defaultEscape = turndown.escape.bind(turndown);
+turndown.escape = (text) => defaultEscape(text).replace(/\\_/g, "_");
+// Turndown's built-in image rule escapes alt text via a private module-level
+// helper, not the overridable `escape` method above, so alt text (often just
+// the image's own filename, e.g. "pitch_positive.png") still comes out with
+// escaped underscores. Same fix, applied to this one rule directly.
+turndown.addRule("unescapedImageAlt", {
+    filter: "img",
+    replacement: (_content, node) => {
+        const el = node;
+        const alt = el.getAttribute?.("alt") ?? "";
+        const src = el.getAttribute?.("src") ?? "";
+        const title = el.getAttribute?.("title");
+        const titlePart = title ? ` "${title.replace(/"/g, '\\"')}"` : "";
+        return src ? `![${alt}](${src}${titlePart})` : "";
+    },
+});
 // ── HTML → Markdown ──────────────────────────────────────────────────
 /**
  * Extract main content from an HTML page and convert to markdown.
@@ -43,7 +95,13 @@ export function htmlToMarkdown(html, url) {
         ? html
         : html.replace(/(<head[^>]*>)/i, `$1<base href="${url}">`);
     const { document } = parseHTML(htmlWithBase);
-    const reader = new Readability(document, { charThreshold: 100 });
+    // classesToPreserve keeps class="pre" (Sphinx's no-wrap marker for inline
+    // literals) alive through Readability's cleanup, so the sphinxPreSpan
+    // Turndown rule above can still detect and unescape it.
+    const reader = new Readability(document, {
+        charThreshold: 100,
+        classesToPreserve: ["pre"],
+    });
     const article = reader.parse();
     if (!article?.content)
         return null;

package/docs/_reference/skillcorner-crunch-help/getting-started-api-access-dynamic-events.md

@@ -0,0 +1,134 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/api-access-dynamic-events
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:38.861Z
+---
+The aim of this page is to guide you when accessing SkillCorner Dynamic Events via SkillCorner API.
+
+The last part of the article provides a code snippet for Python users.
+
+If you have not already, you can start by reading
+
+-   The glossary section dedicated to [Dynamic Events](https://skillcorner.crunch.help/en/glossaries#dynamic-events).
+-   [Our article](https://skillcorner.crunch.help/en/getting-started/first-requests) about the global overview of the SkillCorner API. 
+
+## Dynamic Events CSV and Sportscode XML
+
+SkillCorner delivers two data formats.
+
+-   CSV files that contains either one type of Dynamic Events or all Dynamic Events that occurs during a match. You can access the specifications [here](https://skillcorner.crunch.help/en/glossaries/off-ball-runs-csv-specifications).
+-   Video Analysis XML (Sportscode XML format) files that can be used to track visualise Dynamic Events in video clips in combination with Sportscode, SBG Focus or SBG MatchTracker.
+
+## Using the API
+
+Dynamic events are available through SkillCorner API. 
+
+The API documentation is available [here](https://skillcorner.com/api/docs/#/match/match_dynamic_events_off_ball_runs_list). You can use this page to test the API.
+
+The endpoint are
+
+-   https://skillcorner.com/api/match/{match\_id}/dynamic\_events
+-   https://skillcorner.com/api/match/{match\_id}/dynamic\_events/player\_possessions
+-   https://skillcorner.com/api/match/{match\_id}/dynamic\_events/passing\_options
+-   https://skillcorner.com/api/match/{match\_id}/dynamic\_events/off\_ball\_runs
+
+Where {match\_id} should be replaced with the id of the match you want to access events for.
+
+Example: _https://skillcorner.com/api/match/911858/dynamic\_events_
+
+By default the endpoint returns a CSV file containing the Dynamic Events associated with the match\_id you specified assuming
+
+-   The match was processed
+    
+-   The Dynamic Events Check is passed (see more [here](https://skillcorner.crunch.help/en/getting-started/dynamic-events-check))
+    
+-   There was no error during the generation of the dynamic events.
+    
+
+In order to access the Video Analysis XML, you need to specify the query parameter file\_format with the value “sportscode-xml”.
+
+Example: _https://skillcorner.com/api/match/911858/dynamic\_events/off\_ball\_runs?file\_format=sportscode-xml_
+
+The file should be available within a couple of seconds.
+
+## Manage updates of the Dynamic Events
+
+Via the data\_collection endpoint, you can determine when the dynamic events were last generated.
+
+1.  Send a call to the data\_collection endpoint https://skillcorner.com/api/match/{march\_id}/data\_collection where {match\_id} should be replaced with the id of the match you want to access events for.
+2.  Look for dynamic\_events\_last\_modified in the response.
+3.  The date corresponds to the last time we generated the dynamic events for the specific match ID.
+
+## Using Python
+
+You can use the SkillCorner Python client to access csv and xml files.
+
+-   If you have not installed the package yet go [here](https://skillcorner.crunch.help/en/getting-started/skillcorner-python-client).
+-   Otherwise make sure you upgrade it using the following command  
+    `pip install -U skillcorner`
+
+The Python Client documentation is available [here](https://skillcorner.readthedocs.io/en/latest/getting_started.html).
+
+### Saving a file
+
+Here is a snippet you can use to save the data for a given match ID
+
+-   Replace "your\_username", "your\_password", and "your\_match\_id".
+-   \[optional\] Modify the filepath within the save\_dynamic\_events method if you want to save the files elsewhere
+-   \[optional\] Change the format of the file to "sportscode-xml" and the filepath accordingly to retrieve the xml rather than the csv file.
+
+```
+from skillcorner.client import SkillcornerClient
+
+# Instantiate the client
+username = "your_username"
+password = "your_password"
+client = SkillcornerClient(username=username, password=password)
+
+# Retrieve the data for a given match ID
+match_id = your_match_id 
+
+data_collection = client.get_match_data_collection(match_id)
+
+# The data is available if the "dynamic_events_check" value is True
+if data_collection['dynamic_events_check']:
+    filepath = f"{match_id}.csv"
+    client.save_dynamic_events(match_id, params=
+                                             {
+                                                 'file_format': 'csv'
+                                             },
+                                             filepath=filepath)
+else: 
+    print(f"Match {match_id} does not have Dynamic Events data available")
+
+```
+
+**Opening the CSV**
+
+Here is a snippet you can use to open a csv for a given match ID
+
+-   Replace "your\_username", "your\_password", and "your\_match\_id".
+
+```
+from skillcorner.client import SkillcornerClient
+import pandas as pd
+
+# Instantiate the client
+username = "your_username"
+password = "your_password"
+client = SkillcornerClient(username=username, password=password)
+
+# Retrieve the data for a given match ID
+match_id = your_match_id 
+
+data_collection = client.get_match_data_collection(match_id)
+
+# The data is available if the "dynamic_events_check" value is True
+if data_collection['dynamic_events_check']:
+    file = client.get_dynamic_events(match_id)
+    dynamic_events_df = pd.read_csv(file)
+else: 
+    print(f"Match {match_id} does not have Dynamic Events data available")
+
+```

package/docs/_reference/skillcorner-crunch-help/getting-started-api-access-our-tracking-data.md

@@ -0,0 +1,160 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/api-access-our-tracking-data
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:48.096Z
+---
+This article is about **SkillCorner Tracking v3**.
+
+### X,Y Coordinate Data
+
+The SkillCorner AI platform automatically generates XY tracking data with the origin (0,0) coordinate existing in the exact centre of the pitch as per the XY coordinate pitch map below.
+
+-    The pitch dimension can be retrieved from GET `/api/match` endpoint. ‘pitch\_length’ is the long side of the field while ‘pitch\_width’ is the short side.
+-   The unit of the modelization is the meter, the center of the coordinates is at the center of the pitch.
+-   The x axis is the long side and the y axis is the short side.
+
+![](https://ucarecdn.com/fa23e079-dbde-4e29-8cba-ef4634a8e55f/image.png)
+
+### X,Y file format
+
+The X,Y data can be downloaded with the `/api/match/{match_id}/tracking?data_version=3` endpoint which return the full continuous 22 player extrapolated tracking data.
+
+There are two different formats available for the X,Y tracking data:
+
+**1\. jsonlines file**
+
+[Jsonlines](https://jsonlines.org/) is a file format where each line is a valid json.
+
+In our case, each line is a frame of tracking data represented by a json:
+
+```
+{
+  "frame": 6890,
+  "timestamp": "00:00:00.00",
+  "period": 1,
+  "ball_data": {
+    "x": -1.24,
+    "y": -0.83,
+    "z": 0.44,
+    "is_detected": true
+  },
+  "possession": {
+    "player_id": null,
+    "group": "away team"
+  },
+  "image_corners_projection": {
+    "x_top_left": -45.35,
+    "y_top_left": 39.0,
+    "x_bottom_left": -13.66,
+    "y_bottom_left": -34.29,
+    "x_bottom_right": 13.41,
+    "y_bottom_right": -34.17,
+    "x_top_right": 44.04,
+    "y_top_right": 39.0
+  },
+  "player_data": [
+    {
+      "x": -39.75,
+      "y": -0.75,
+      "player_id": 12543,
+      "is_detected": false
+    },
+    {
+      "x": -19.52,
+      "y": -8.15,
+      "player_id": 1733,
+      "is_detected": true
+    },
+...
+    {
+      "x": -11.75,
+      "y": -2.99,
+      "player_id": 12190,
+      "is_detected": false
+    },
+    {
+      "x": 0.13,
+      "y": -31.8,
+      "player_id": 6028,
+      "is_detected": true
+    }
+  ]
+}
+
+```
+
+The keys are:
+
+**Keys**
+
+**Description**
+
+**frame**
+
+ID of the frame
+
+**timestamp**
+
+Match timestamp, null if outside of the playing time
+
+**period**
+
+Period of the match (1: first half, 2: second half, 3: first OT half, 4: second OT half)
+
+**ball\_data**
+
+• Ball Coordinates (x,y,z)
+
+• Define if the ball is detected (is\_detected\=TRUE) or purely extrapolated (is\_detected\=FALSE)
+
+**possession**
+
+Contains the player and the team 
+
+• Player ID of the player in possession : player
+
+• Team in possession : group, equal to "home", "away" or empty if ball is out of play
+
+**image\_corners\_projection**
+
+Coordinates of the 4 corners of the polygon from the projection of the camera field onto the ground (white circles on the image below).
+
+**![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeDlHdpYzNnMJZyBNTqbza1KhKsO3rBAPnHmh077Uu0psOjXDcB9nXYXD0EzgNNs-ZfqEbk1_r3tPPgW26joE0bJW4V-ICUkk5TQYG1Q8I66_bBlmSmpPLodDLuN-fNeOatqcHIVEAsCkdSUM0y5H-b8zvn?key=m8sstDl0eDdxU3EFSvVz2A)**
+
+**player\_data**
+
+Provides for each player on the pitch
+
+• Player ID : player\_id
+
+• Player Coordinates : x,y
+
+• Whether the player is detected (is\_detected\=TRUE) or purely extrapolated (is\_detected\=FALSE)
+
+The match data coming from endpoint `/api/match/{match_id}` also includes a home\_team\_side key which give the direction of attack of the home team for each period. It’s a list of size equal to the number of period (2 on a regular match and 4 if there was extra time). The value is left\_to\_right if the home team attack on the right side, right\_to\_left otherwise.
+
+**2\. Plain text file (built according to FIFA’s Electronic Performance and Tracking Systems (EPTS)).**
+
+The FIFA EPTS format is composed of two files. One file is a xml specifying general information on the match, and the format of the txt file. The other file is the data file with all the tracking data.
+
+The xml file includes general information:
+
+-   start and end frame of each period
+-   pitch dimension
+-   the direction of attack of each team
+-   the identifier for each player
+
+The file also includes the specification of each column in the data file which is in the key DataFormatSpecifications.
+
+There are multiple specifications in a match. Each time a player is red carded or substituted, there is a new specification.
+
+Each specification indicates the start frame and the end frame in the data file. For each specification, you have the list of the column in the data file and which separator is used. Note that the data file is not a regular csv and is using different separator that are documented in the xml file.
+
+### Quality Index
+
+The quality index is a proxy for the accuracy of our continuous 22 player extrapolated tracking data.
+
+For each match, there are two quality indexes, one measuring the ball tracking quality and one measuring the player tracking quality. When we want a general quality index, we generally take the minimum of these two values.
+
+These values can be found in the data collection endpoint `/api/match/{match_id}/data_collection`.

package/docs/_reference/skillcorner-crunch-help/getting-started-best-practice-analysis-guidance.md

@@ -0,0 +1,16 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/best-practice-analysis-guidance
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:54.189Z
+---
+The SkillCorner delivery tools provide the user with total flexibility on how they wish to analyse and report the data. However, given the constraints of broadcast tracking and the extrapolation models we would recommend the following:
+
+-   For benchmarking by competition/league/position/age group, you should filter performances over 60 or 70 mins duration – this will ensure the benchmarks have very good validity.
+    
+-   For analyzing individual performance, we do not recommend including performances less than 30 mins duration, and would normally suggest 45 mins as an absolute minimum to ensure good results.
+    
+-   For calculating player averages, we would generally suggest using 10 matches as a minimum – calculating the standard error of the mean can be used to measure the accuracy with which a sample distribution represents a population.
+    
+
+To learn more about the constrains of broadcast tracking and our approach to delivering reliable data, go to [this article](https://skillcorner.crunch.help/en/working-with-the-data/data-quality-standards).

package/docs/_reference/skillcorner-crunch-help/getting-started-dynamic-events-check.md

@@ -0,0 +1,33 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/dynamic-events-check
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:51.074Z
+---
+## Definition
+
+In order to ensure you work only with trustworthy data we have put in place a quality check named Dynamic Events Check. 
+
+The Dynamic Events Check can have three values
+
+-   _True_ when the match has been processed and the Dynamic Events are of good quality
+    
+-   _False_ when the match has been processed and the Dynamic Events may not be trustworthy
+    
+-   _None_ when the match has not been processed either because of an error or because we miss input to process it
+    
+
+**We deliver Dynamic Events when the Dynamic Events Check is True.** Otherwise we don’t as we want to make sure our users are not misled by erroneous data.
+
+Defined at match level the Dynamic Events Check takes into account
+
+-   The quality of the SkillCorner Tracking Data for that match (the quality index of the tracking and the ball need to be at least equal to 4)
+-   The percentage of Wyscout events we are able to match with our own tracking.
+
+## Access the Dynamic Events Check value
+
+The value of the Dynamic Events Check is available via the data collection endpoint https://skillcorner.com/api/match/{match\_id}/data\_collection where {match\_id} should be replaced with the id of the match you want to access events for. 
+
+Look for the _dynamic\_events\_check_ key in the json response.
+
+If you are using Python, you can use [get\_match\_data\_collection()](https://skillcorner.readthedocs.io/en/latest/skillcorner_client.html#skillcorner.client.SkillcornerClient.get_match_data_collection) method form SkillCorner Python client.

package/docs/_reference/skillcorner-crunch-help/getting-started-explore-game-intelligence-data-1.md

@@ -0,0 +1,37 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/explore-game-intelligence-data-1
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:46.947Z
+---
+The aim of this page is to guide you when accessing our In-possession data.
+
+If you have not already, you can start by reading [our article](https://skillcorner.crunch.help/en/getting-started/first-requests) about the global overview of the SkillCorner API. 
+
+## Look for insights regarding Off-Ball runs
+
+A good way to start is by requesting data for players from your own team.  
+
+As an example, we will therefore access data from the French team Stade Lavallois, that played in Ligue 2 for the 2022/23 season and evaluate their off-ball runs abilities when a team-mate is in possession.
+
+To do so, we will need to start by requesting the [/competitions/](https://skillcorner.com/api/docs/#/competitions/competitions_list), [/competitions/{competition\_id}/editions/](https://skillcorner.com/api/docs/#/competitions/competitions_editions_list) and [/teams/](https://skillcorner.com/api/docs/#/teams/teams_list) endpoints to find the relevant IDs.
+
+As you can see in the video below, here are the corresponding IDs:
+
+-   French Ligue 2: 12
+-   Ligue 2 2022/23 season: 393
+-   Stade Lavallois: 735
+
+The next step is to request the [/in\_possession/off\_ball\_runs/](https://skillcorner.com/api/docs/#/in_possession/in_possession_off_ball_runs_list) endpoint to access the data of interest.
+
+**Recommended readings  
+**Before going further, we advise you to have a look to:  
+  
+\- The [definitions](https://skillcorner.crunch.help/en/glossaries/running-off-ball-metrics-1) of our off-ball running metrics  
+\- The [run types](https://skillcorner.crunch.help/en/glossaries/run-detection-and-classification) we detect  
+\- Our [modelisation](https://skillcorner.crunch.help/en/glossaries/pitch-modelisation) of the pitch  
+\- The [methodology](https://skillcorner.crunch.help/en/glossaries/averaging-per-match-per-events-or-per-min) regarding metrics averages
+
+This will give you a good overview of the concepts behind the run\_type, channel and average\_per parameters.
+
+Let see the results for Stade Lavallois, by focusing on Runs in behind in the attacking third:

package/docs/_reference/skillcorner-crunch-help/getting-started-explore-game-intelligence-data.md

@@ -0,0 +1,29 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/explore-game-intelligence-data
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:39.464Z
+---
+The aim of this page is to guide you when accessing our In-possession data.
+
+If you have not already, you can start by reading [our article](https://skillcorner.crunch.help/en/getting-started/make-your-first-queries) about the global overview of the SkillCorner Web App. 
+
+## Look for insights regarding Off-Ball runs
+
+A good way to start is by requesting data for players from your own team.
+
+As an example, we will therefore access data from the French team Stade Lavallois, that played in Ligue 2 for the 2022/23 season and evaluate their off-ball runs abilities when a team-mate is in possession.
+
+To do so, we will need to select the Running Off-Ball tab from the main menu.  
+The set up of the request will be similar to a one regarding Physical metrics.
+
+**Recommended readings  
+**Before diving into this section, we advise you to have a look to:  
+  
+\- The [definitions](https://skillcorner.crunch.help/en/glossaries/running-off-ball-metrics-1) of our off-ball running metrics  
+\- The [run types](https://skillcorner.crunch.help/en/glossaries/run-detection-and-classification) we detect  
+\- Our [modelisation](https://skillcorner.crunch.help/en/working-with-the-data/pitch-modelisation) of the pitch  
+\- The [methodology](https://skillcorner.crunch.help/en/working-with-the-data/averaging-per-match-per-events-or-per-min) regarding metrics averages
+
+This will give you a good overview of the concepts behind the _Run types_, _Pitch zone_ and _Average metrics per_ filters.  
+Let see the results by focusing on Runs in behind in the attacking third:

package/docs/_reference/skillcorner-crunch-help/getting-started-first-requests.md

@@ -0,0 +1,99 @@
+---
+source_url: https://skillcorner.crunch.help/en/getting-started/first-requests
+source_type: crunch_help_kb
+upstream_version:
+crawled_at: 2026-07-13T14:06:41.936Z
+---
+The aim of this page is to give you an overview of the requests available and guide you through your first steps.
+
+You can start by accessing the detailed documentation of the SkillCorner API: [https://skillcorner.com/api/docs/](https://skillcorner.com/api/docs/)
+
+Since it enables you to send API queries, we recommend using the documentation for debugging purposes and testing API calls before implementation.
+
+## Python client
+
+In order to use the SkillCorner API, we also provide a Python client to help you set up more easily.  
+You will find the relevant articles [here](https://skillcorner.crunch.help/en/getting-started/skillcorner-python-client).
+
+## Authentication
+
+The API supports two types of authentication: 
+
+-   **Recommended**  
+    The basic Authentication allows you to sign in using the same username and password that you might already use to access  
+    the [Web App](https://skillcorner.com/app/login).
+    
+-   Using an API Key, based on a token provided by SkillCorner upon request. Once authorized, the token is passed as a parameter within queries.
+
+If you have questions regarding authentication, you can [send us an email](mailto:support@skillcorner.com).
+
+## API Organization
+
+When accessing the API, a series of endpoints is available, including the relevant parameters and response formats.
+
+The API is currently organised as follows:
+
+-   Competition editions: to list the competition editions (e.g. AUT Bundesliga 21/22) you can access.  
+    
+-   In Possession package: to access our In-possession data, focusing on off-ball runs, passes and on-ball pressure aggregates  ([more details here](https://skillcorner.crunch.help/en/glossaries#in-possession-1)).
+-   Match: to access match data.
+-   Matches: to list the matches available.
+-   Physical: to access our Physical data ([more details here](https://skillcorner.crunch.help/en/glossaries#physical)).
+-   Players: to list the players available in our database.
+-   Roles: to list the SkillCorner roles and positions ([more details here](https://skillcorner.crunch.help/en/working-with-the-data/physical-data-glossary-1-1)).
+-   Seasons: to list the seasons ids (e.g. 2021/22).
+-   Teams: to list the teams available in our database.
+
+## Accessing the available competitions
+
+As an example, let say that my goal is to access the physical data of players from French side OGC Nice and their opponents, on the last gameweek of the 2021/2022 season.
+
+**Permission management  
+**Depending on your current subscription, you will only be able to obtain data for specific competitions, matches and packages.
+
+In our case, we will need to start by requesting the /competitions/ endpoint and list all competitions. This will allow us to find the ID corresponding to the French Ligue 1.
+
+Given our request, no specific parameter is needed and we can launch it by hitting "Try it out", then "Execute".
+
+**API rate limit  
+**Please note that our API allows you to make up to **15 requests** per **second**.
+
+For the French Ligue 1, we notice that the corresponding ID is **3**:
+
+If we focus on the response, we find three elements of interest:
+
+![](https://ucarecdn.com/6af2443a-511e-4686-ba3c-84fc1434a546/API.png)
+
+-   The request URL  
+    
+-   The request results
+-   Pagination elements (as per default, one can only retrieve batches of up to 100 elements per request).
+
+## Retrieving matches from a specific competition edition
+
+Now that we have the ID corresponding to the FR Ligue 1 (3), we will then be able to: 
+
+-   Find the ID of the competition edition we are looking for (Ligue 1 - 2021/22) from the /competitions/{competition\_id}/editions/ endpoint.
+-   We notice that the corresponding ID is **242:**
+
+-   The next step is to list all the matches of this competition edition (242), from the /matches/ endpoint
+-   Then find the match ID that we are looking for
+
+For the last game of the season for OGC Nice, we notice that the corresponding ID is **129597:**
+
+## Accessing the physical data of a specific match
+
+The last step of our example is to request the physical data from the /physical/ endpoint, using the match ID 129597:
+
+Here, we can add specific parameters to focus on different aspects of the game such as the number of minutes played, time in possession/out of possession or the period.
+
+You can find more details about physical metrics [here](https://skillcorner.crunch.help/en/glossaries/physical-data-glossary).
+
+From the documentation interface, you also have the opportunity to download the request response if needed:
+
+## Accessing the physical data at the player level
+
+As a second and final example, we will focus on players rather than teams.   
+Our goal will be to retrieve data averages per player, in Ligue 1, for the 2021/2022 season.
+
+Using the /physical/ endpoint, and by setting the average parameter at true after filling in the competition\_edition value (242 for the Ligue 1 21/22), we will retrieve the following results: