feat: adding direct queries

examples/direct/example_use.ipynb

@@ -0,0 +1,285 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a81bd7ff",
+   "metadata": {},
+   "source": [
+    "# Using the PlayerData API with Direct\n",
+    "\n",
+    "This notebook demonstrates how to use the PlayerData API with Direct Queries to query session details and raw data.\n",
+    "\n",
+    "## Prerequisites\n",
+    "\n",
+    "Before using this notebook, you will need to:\n",
+    "- Create a virtual environment\n",
+    "- Install all dependencies from the `pyproject.toml` file\n",
+    "\n",
+    "## Authentication\n",
+    "\n",
+    "First, we need to authenticate with the PlayerData API. There are three authentication methods available:\n",
+    "\n",
+    "1. **Client Credentials Flow** (shown in this example)\n",
+    "2. **Authorization Code Flow**\n",
+    "3. **Authorization Code Flow with PKCE**\n",
+    "\n",
+    "To use a different authentication method, change the `authentication_type` parameter to `AuthenticationType.AUTHORIZATION_CODE_FLOW` or `AuthenticationType.AUTHORIZATION_CODE_FLOW_WITH_PKCE` and provide the required parameters."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "227644c3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from playerdatapy.gqlauth import GraphqlAuth\n",
+    "from playerdatapy.gqlauth import AuthenticationType\n",
+    "from playerdatapy.gqlclient import Client\n",
+    "from playerdatapy.constants import API_BASE_URL\n",
+    "\n",
+    "# Add your client id, client secret and one of your club ids\n",
+    "CLIENT_ID = \"your_client_id\"\n",
+    "CLIENT_SECRET = \"your_client_secret\"\n",
+    "CLUB_ID = \"your_club_id\"\n",
+    "\n",
+    "# Example usage of the GraphqlClient class.\n",
+    "auth = GraphqlAuth(\n",
+    "    client_id=CLIENT_ID,\n",
+    "    client_secret=CLIENT_SECRET,\n",
+    "    type=AuthenticationType.CLIENT_CREDENTIALS_FLOW,\n",
+    ")\n",
+    "\n",
+    "# Create a Client instance.\n",
+    "client = Client(\n",
+    "    url=f\"{API_BASE_URL}/api/graphql\",\n",
+    "    headers={\"Authorization\": f\"Bearer {auth._get_authentication_token()}\"},\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "66e76500",
+   "metadata": {},
+   "source": [
+    "## Defining Queries\n",
+    "\n",
+    "There are example queries in the `queries` folder that you can use as a starting point. For example, `ClubSessionsFilteredByTimeRange` retrieves all sessions for a club in a specified time period."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a8f0c3d1",
+   "metadata": {},
+   "source": [
+    "## Running Example Queries\n",
+    "\n",
+    "For now, let's use the example queries, run them, and print the results."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4534adda",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import datetime, timedelta\n",
+    "\n",
+    "with open(\"queries/club_sessions_filtered_by_time_range.graphql\", \"r\") as f:\n",
+    "    club_sessions_filtered_by_time_range = f.read()\n",
+    "\n",
+    "# Query for all sessions in the last 30 days\n",
+    "start_time = datetime.now() - timedelta(days=30)\n",
+    "end_time = datetime.now()\n",
+    "\n",
+    "last_thirty_days_sessions_response = await client.execute(\n",
+    "    query=club_sessions_filtered_by_time_range,\n",
+    "    variables={\"clubId\": CLUB_ID, \"startTime\": start_time, \"endTime\": end_time},\n",
+    ")\n",
+    "\n",
+    "last_thirty_days_sessions_response = client.get_data(last_thirty_days_sessions_response)\n",
+    "\n",
+    "print(last_thirty_days_sessions_response)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "15a1ca44",
+   "metadata": {},
+   "source": [
+    "## Getting Session Details\n",
+    "\n",
+    "From the response above, we can see the sessions returned. Now let's get detailed information for a specific session using the session ID from the first session in the response."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8a8ef4b4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with open(\"queries/session_details.graphql\", \"r\") as f:\n",
+    "    session_details = f.read()\n",
+    "\n",
+    "# Extract the session ID from the first session\n",
+    "first_session_id = last_thirty_days_sessions_response[\"sessions\"][0][\"id\"]\n",
+    "\n",
+    "session_details_response = await client.execute(\n",
+    "    query=session_details, variables={\"sessionId\": first_session_id}\n",
+    ")\n",
+    "\n",
+    "session_details_response = client.get_data(session_details_response)\n",
+    "print(session_details_response)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1a947b52",
+   "metadata": {},
+   "source": [
+    "## Getting Session Metrics\n",
+    "\n",
+    "For the same session, you can retrieve configured metrics at different levels:\n",
+    "- Team aggregate level\n",
+    "- Session participation level\n",
+    "- Segment level"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4f9f7708",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with open(\"queries/session_metrics.graphql\", \"r\") as f:\n",
+    "    session_metrics = f.read()\n",
+    "\n",
+    "# Query for session metrics at all levels\n",
+    "session_metrics_response = await client.execute(\n",
+    "    query=session_metrics, variables={\"sessionId\": first_session_id}\n",
+    ")\n",
+    "\n",
+    "session_metrics_response = client.get_data(session_metrics_response)\n",
+    "print(session_metrics_response)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9c5c065e",
+   "metadata": {},
+   "source": [
+    "## Advanced Usage: Raw Data\n",
+    "\n",
+    "To query for raw data, you can use the `session_participation_urls` query. This returns URLs for the raw data for a given list of session participation IDs.\n",
+    "\n",
+    "We'll use the first session participation ID from the `session_details_response`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1730ccec",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with open(\"queries/session_participations_urls.graphql\", \"r\") as f:\n",
+    "    session_participations_urls = f.read()\n",
+    "\n",
+    "# Extract the first session participation ID\n",
+    "first_session_participation_id = session_details_response[\"session\"][\n",
+    "    \"sessionParticipations\"\n",
+    "][0][\"id\"]\n",
+    "\n",
+    "# Query for raw data URLs\n",
+    "session_participation_urls_response = await client.execute(\n",
+    "    query=session_participations_urls,\n",
+    "    variables={\"ids\": [first_session_participation_id]},\n",
+    ")\n",
+    "\n",
+    "session_participation_urls_response = client.get_data(\n",
+    "    session_participation_urls_response\n",
+    ")\n",
+    "print(session_participation_urls_response)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "96aafdd9",
+   "metadata": {},
+   "source": [
+    "## Downloading Raw Data\n",
+    "\n",
+    "The response contains a list of URLs for the raw data for the given session participation ID.\n",
+    "\n",
+    "You can download the raw JSON data in two ways:\n",
+    "1. Use the `url_to_csv` function from `raw_data_utils.url_to_csv.py` (shown below)\n",
+    "2. Use the `requests` library directly\n",
+    "\n",
+    "The `url_to_csv` function downloads the raw JSON data from the URL and saves it to CSV files:\n",
+    "- One file for GPS data\n",
+    "- One file for IMU acceleration data\n",
+    "- One file for IMU orientation data\n",
+    "\n",
+    "The session participation ID is used as a prefix in the filename to differentiate between files."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec55f919",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "from pathlib import Path\n",
+    "\n",
+    "# Add project root to Python path to get access to url_to_csv package\n",
+    "# Only required for notebook example\n",
+    "sys.path.append(str(Path().resolve().parent))\n",
+    "from raw_data_utils.url_to_csv import url_to_csv\n",
+    "\n",
+    "# Extract the URL from the first session participation\n",
+    "first_session_participation_url = session_participation_urls_response[\n",
+    "    \"sessionParticipations\"\n",
+    "][0][\"datafiles\"][0][\"url\"]\n",
+    "\n",
+    "# Download and convert raw data to CSV files\n",
+    "url_to_csv(first_session_participation_url, first_session_participation_id)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "706f8730",
+   "metadata": {},
+   "source": [
+    "This will create a folder in your root directory with the session participation ID and the three CSV files saved inside.\n",
+    "\n",
+    "**Note:** This method of retrieving raw data via the API is currently only available for GPS and IMU data. This method will be deprecated in the future, making way for a simpler method of raw data retrieval where raw LPS data will also be available."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/direct/queries/club_sessions_filtered_by_time_range.graphql

@@ -0,0 +1,7 @@
+query ClubSessionsFilteredByTimeRange($clubId: ID, $startTime:ISO8601DateTime,$endTime:ISO8601DateTime){
+	sessions(filter: {clubIdEq: $clubId, startTimeGteq: $startTime, endTimeLteq:$endTime}, offset: 0, limit:30){
+    id
+    startTime
+    endTime
+  }
+}

examples/direct/queries/session_details.graphql

@@ -0,0 +1,19 @@
+query SessionDetails($sessionId: ID!) {
+  session(id: $sessionId) {
+    sessionParticipations {
+      id
+      athlete {
+        id
+        name
+      }
+      segmentParticipations {
+        segment {
+          id
+          title
+          startTime
+          endTime
+        }
+      }
+    }
+  }
+}

examples/direct/queries/session_metrics.graphql

@@ -0,0 +1,66 @@
+query SessionMetrics($sessionId: ID!) {
+  session(id: $sessionId) {
+    startTime
+
+    configuredAggMetrics {
+      data {
+        label
+        localUnitLabel
+        localValue {
+          ... on FloatMetricValue {
+            floatValue
+          }
+          ... on IntMetricValue {
+            intValue
+          }
+          ... on JsonMetricValue {
+            jsonValue
+          }
+        }
+      }
+    }
+
+    sessionParticipations {
+      configuredMetrics {
+        data {
+          label
+          localUnitLabel
+          localValue {
+            ... on FloatMetricValue {
+              floatValue
+            }
+            ... on IntMetricValue {
+              intValue
+            }
+            ... on JsonMetricValue {
+              jsonValue
+            }
+          }
+        }
+      }
+
+      segmentParticipations {
+        segment {
+          title
+        }
+        configuredMetrics {
+          data {
+            label
+            localUnitLabel
+            localValue {
+              ... on FloatMetricValue {
+                floatValue
+              }
+              ... on IntMetricValue {
+                intValue
+              }
+              ... on JsonMetricValue {
+                jsonValue
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

examples/direct/queries/session_participations_urls.graphql

@@ -0,0 +1,8 @@
+query SessionParticipationsUrls($ids: [ID!]!) {
+  sessionParticipations(ids: $ids) {
+    id
+    datafiles {
+      url(format: json)
+    }
+  }
+}