Package: sdvclient
Sport Data Valley client library for PythonIntroductionsdvclientis a Python client library for the Sport Data Valley platform.
It is basically a wrapper around the REST API (documentedhere).InstallationIf you are working in the Sport Data Valley JupyterHub environment, this library is automatically installed.If you are working in a different Python environment, this library can be installed fromPyPI:pipinstallsdvclientWhen you have previously installed the library and want to upgrade to a newer version:pipinstall--upgradesdvclientUsageimportsdvclientassdvfordatasetinsdv.my_datasets():# Do somethingpassThe dataset summaries that are returned frommy_datasets()have attributes liketitle,event_start,event_end,owner,sport,tagsand more...dataset.sport>>>"sports.riding"To retrieve data from your network:importsdvclientassdvfordatasetinsdv.network_datasets():# Do somethingpassTo retrieve data from a specific group in your network (see below for how to retrieve these groups):importsdvclientassdvfordatasetinsdv.group_datasets():# Do somethingpassLimit the number of resultsBothsdv.my_datasets(),sdv.network_datasets()andsdv.group_datasets()accept an optionallimitargument that can be used to limit the number of dataset summaries that are returned.importsdvclientassdvfordatasetinsdv.my_datasets(limit=10):# Process maximum 10 datasetspassPlease note that if there are less datasets available then thelimityou specify, the number of returned dataset summaries is lower thanlimit.Filter network datasdv.network_datasets()accepts an optionalqueryargument that can be used to filter the returned datasets:importsdvclientassdvfordatasetinsdv.network_datasets(query="strava"):# Process datasets that are matched by the "strava" querypassPlease note that the query argument filters onallthe fields of a dataset.
This means that filtering on the name of a user does not necessarily only retrieve data for that user, as this name may also occuranywhereelse in a different dataset.N.B. Thequeryargument isnotavailable forsdv.my_datasets().Retrieve groups and connectionsTo retrieve the groups in your network:importsdvclientassdvforgroupinsdv.groups():# Do somethingpassTo retrieve the connections in your network:importsdvclientassdvforconnectioninsdv.connections():# Do somethingpassWhen you found a connection that you want to retrieve data for you can retrieve those like this:importsdvclientassdvfordatasetinsdv.connection_datasets(user=connection):# Do somethingpassTheconnectioninput argument is aUserobject that can come fromsdv.connections()or from thedataset.ownerfrom a previous request.Please be aware that this method usessdv.network_datasets()under the hood and can therefore be slow when you have a lot of datasets from other connections.Retrieving raw/full dataAfter you have retrieved a dataset summary, you can then continue to download the raw/full data from this dataset by calling theget_data()method on this object:importsdvclientassdvfordatasetinsdv.my_datasets():full_data=dataset.get_data()Or you can retrieve the raw/full data directly if you know the dataset id:importsdvclientassdvfull_data=sdv.get_data(id=1337)Every object that is returned fromget_data()has attributes liketitle,event_start,event_end,owner,sport,type,tagsand more fields depending on the data_type. For example a dataset with typestrava_typehas an attributedataframethat contains apandas.DataFramewith the data from this dataset.dataset.data_type>>>"strava_type"dataset.dataframe>>><pandas.DataFrame>Strava data typeAs mentioned above, dasets of typestrava_typehave an attribute dataframe with the corresponding data in a dataframe:dataset.data_type>>>"strava_type"dataset.dataframe>>><pandas.DataFrame>Questionnaire data typeDatasets of type questionnaire have aquestionsattribute which contains of all the questions and answers in the questionnaire.
For each question+answer, the question and answer are available on thequestionandanswerattributes, respectivily.dataset.questions[2].question>>>"this is a question"dataset.questions[2].answer>>>"this is an answer"Generic CSV data typeFor generic tabular data like csv's the returned dataset has an attribute dataframe with the corresponding data in a dataframe:dataset.data_type>>>"generic_csv_type"dataset.dataframe>>><pandas.DataFrame>Daily activity data typeFor daily activity data that is coming from e.g. Fitbit or Polar, the returned dataset has a range of attributes:stepsdistancecaloriesfloorssleep_startsleep_endsleep_durationresting_heart_rateminutes_sedentaryminutes_lightly_activeminutes_fairly_activeminutes_very_activedataset.data_type>>>"fitbit_type"dataset.resting_heart_rate>>>58Please note that not all attributes are always available, this is platform and device dependent.Unstructured dataUnstructured data is data (files) that Sport Data Valley does not know how to process.
These files are stored "as is" in the platform and can be download via this client library as well:
For generic tabular data like csv's the returned dataset has an attribute dataframe with the corresponding data in a dataframe:
Unstructured data has afile_responseattribute that contains arequests.Responseobject.dataset.data_type>>>"unstructured"dataset.file_response>>><Response[200]>Read more about processing files downloaded with the Python requests libraryhere.
E.g. to process binary response content, seehere.Other data typesAlthough this library will be updated when new data types are added it can happen that a specific data type is not fully supported yet. In that case the returned dateset will be identical as unstructured data, with anfile_responseattribute that contains arequests.Responseobject.
Unstructured data is data (files) that Sport Data Valley does not know how to process.dataset.data_type>>>"some new data type"dataset.file_response>>><Response[200]>AuthenticationThe library retrieves your API token from theSDV_AUTH_TOKENenvironment variable.
If you are working in the Sport Data Valley JupyterHub, this is automatically set.
If you are working in a different environment, you can retrieve an API token from the "Advanced" pagehereand set it like this:sdv.set_token("your API token here")DevelopmentAdding Python versionsThe supported Python versions are specified inpyproject.toml[tool.poetry.dependencies]#python.
The Python versions that are tested are specified inpyproject.toml[tool.tox]#envlistand inDockerfile.test.
If you want to add a new supported Python version, or want to test against a newer version of an existing Python version, the versions at these locations need to be updated.ContributorsAart GoossensLicenseSeeLICENSEfile.