Get in touch

Get in touch

Prefer using email? Say hi at hello@moveshelf.com

Developer

    Search Knowledge Base
Getting started
  • Setting up the environment
  • Setting up the Moveshelf API
  • Setting up a GitHub repository
  • Using the API
  • Moveshelf API documentation
  • Configuration and authentication
  • Basic example
  • Advanced example
  • Examples provided by Moveshelf
  • Import
  • Create subject
  • Import subject metadata
  • Query
    Processing script example
  • Download data
  • knowledgebase home

    Moveshelf is designed to keep data secure but always accessible. This is true both from our web interface, for physicians and clinical operators, as well as programmatically from our API, for engineers and scientists. This chapter contains all information to get started with the Moveshelf Python API (from now on referred to as Moveshelf API). The Moveshelf API simplifies integration with Moveshelf for Python developers. It abstracts authentication, request handling, and common tasks into an intuitive, high-level interface, allowing developers to focus on building solutions without needing to manage the complexities of API interactions. The Moveshelf API enables seamless data retrieval and manipulation while integrating naturally with Python's extensive ecosystem of libraries. This makes it an ideal choice for automating workflows, processing data, and creating custom scripts that interact with Moveshelf resources. This documentation is intended for engineers, researchers, and advanced users who want to automate workflows and build custom solutions using the Moveshelf API.
    How to use this documentation
    Our goal is to break down import and querying steps into modular "puzzle pieces" that can be combined to create custom workflows. To get started, read how you can set up your programming environment, the Moveshelf API, and a GitHub repository. Then, learn how to configure the Moveshelf API and where to find a link to the complete documentation. Finally, experiment with specific examples to get started. Each example includes prerequisites that must be completed before implementation. A complete overview of this chapter's sections is available in the navigation menu on the left.



    Setting up the environment
    To interact with the Moveshelf API, you need Python and an IDE (e.g., Visual Studio Code). This setup will allow you to run existing Python scripts from GitHub or create your own. This section walks you through setting up your environment to interact with the Moveshelf API using Python, and running a python script.
    Install programs
    • Visual Studio Code
      • Install Python extension
    • Python
      • Close Visual Studio Code before installing.
      • Make sure you have selected "Add to PATH" during the install process.



    Run a Python script
    • To run a Python script, write the following command in the terminal: python <path/to/your/script.py>, and press 'Enter'


     

    Setting up the Moveshelf API
    This section walks you through the steps you need to execute the first time you want to use the Moveshelf API.
    Installation
    You can install the Moveshelf API directly via PyPI. To do so, run the following command in the terminal:
    • pip install moveshelf-api
    Creating an access key
    Before you can use the Moveshelf API, you need to create an access key:
    • Go to your profile page on Moveshelf (top-right corner)
    • Follow instructions to generate an API key (enter ID for the new key), and click 'Generate API Key'
    • Download the API key file and save 'mvshlf-api-key.json' in the root folder of your Git folder
    Setting up 'mvshlf-config.json'
    Additionally, you need a file called 'mvshlf-config.json', saved in the same folder as 'mvshlf-api-key.json', with the following content:
    {
    	"apiKeyFileName":"mvshlf-api-key.json",
    	"apiUrl":"",
    	"application":"None"
    }
    where the field "apiUrl" should have one of the following values:
    • EU region:
      • StagingTesting environment used to experiment with Moveshelf's application
        : "https://api.staging.moveshelf.com/graphql"
      • ProductionEnvironment containing clinical and/or research data. Not used for testing
        : "https://api.moveshelf.com/graphql"
    • US region:
      • Staging: "https://api.us.staging.moveshelf.com/graphql"
      • Production: "https://api.us.moveshelf.com/graphql"

    Your root folder should look similar to the folder below, where your processing scripts are inside a folder, e.g., 'scripts':


     

    Setting up a GitHub repository
    While using a Git repository is not required to use the Moveshelf API, it provides easy access to public resources from Moveshelf, e.g., moveshelf-data-examples. This section explains how to clone a GitHub repository and install its dependencies.
    Clone a GitHub repository to your local machine
    • Create an account on GitHub to be able to use the public repositories
    • Open a public GitHub repository, e.g., moveshelf-data-examples and copy the repository URL


    • Open Visual Studio Code
      • Press: CTRL + Shift + P
      • Type 'Git: clone’ in the top bar
      • Press ‘Enter’
    • Paste the repository URL and press 'Enter'


  • Select a local folder where you want to clone the repository

  • Install dependencies
    To ensure your Python script runs without errors, it's best practice to list all required modules (along with their versions) in a requirements.txt file. To install these dependencies automatically:
    • Open a new terminal in Visual Studio Code


    • Run the command: pip install -r requirements.txt in the terminal and press 'Enter'
      • Make sure your terminal is in the correct folder where the requirements are saved as well.



     

    Moveshelf API documentation
    While this page covers a variety of examples of basic and advanced API usage, you can find a complete overview of the functions that are available in the Moveshelf API here.


     

    Configuration and authentication
    In this section we will explain how you can import the Moveshelf API into your processing script to securely interact with Moveshelf.
    Prerequisites
    Before implementing this example, ensure that you have performed all necessary setup steps. In particular, you should have:
    Configure the Moveshelf API
    Add the following lines of code to your processing script to use the Moveshelf API:
    import os, sys, json
    parent_folder = os.path.dirname(os.path.dirname(__file__))
    sys.path.append(parent_folder)
    from moveshelf_api.api import MoveshelfApi
    
    ## Setup the API
    # Load config
    personal_config = os.path.join(parent_folder, "mvshlf-config.json")
    if not os.path.isfile(personal_config):
        raise FileNotFoundError(
            f"Configuration file '{personal_config}' is missing.\n"
            "Ensure the file exists with the correct name and path."
        )
    
    with open(personal_config, "r") as config_file:
        data = json.load(config_file)
    
    api = MoveshelfApi(
        api_key_file=os.path.join(parent_folder, data["apiKeyFileName"]),
        api_url=data["apiUrl"],
    )


     

    Basic example
    In this section we will show how you can use built-in functions of the Moveshelf API.
    Prerequisites
    Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:
    Use built-in functions of the Moveshelf API
    In this example we are going to use a built-in function of the Moveshelf API to retrieve the projects the current user has access to. Add the following line of code to get a list of all the projects that are accesible by the user:
    ## Get available projects
    projects = api.getUserProjects()


     

    Advanced example
    In this section we will show how you can adapt the Moveshelf API to your own use cases by implementing your own functions.
    Prerequisites
    Before implementing this example, ensure that you have performed all necessary setup steps. In particular, you should have:
    Extend the Moveshelf API with a custom query
    If you need queries that are not included in the Moveshelf API, you can create a custom API wrapper that extends it with custom GraphQL queries. This section demonstrates how to create a custom API wrapper defining a new method (getProjectSubjectsCustom) to retrieve, for a given project, all subjects' name, ID, and metadata, and all their sessions' ID, date, and metadata.

    Create a custom API wrapper:
    Create a new Python file (in this example we call it api.py and place it inside a folder called 'api' in the root folder), and define a subclass of MoveshelfApi (see code snippet below). This allows you to extend the existing API by adding custom GraphQL queries. For example, the built-in getProjectSubjects function only retrieves subject names and IDs. In the example below, we define getProjectSubjectsCustom, that extends the built-in getProjectSubjects function to also retrieve subject metadata and session details (ID, date, and metadata).

    from moveshelf_api.api import MoveshelfApi
    
    # Custom Moveshelf API class that extends the existing API
    
    class MoveshelfApiCustomized(MoveshelfApi):
    
        def getProjectSubjectsCustom(self, project_id):
            data = self._dispatch_graphql(
                '''
                query getProjectPatients($projectId: ID!) {
                    node(id: $projectId) {
                        ... on Project {
                            id,
                            name,
                            description,
                            canEdit,
                            patients {
                                id
                                name
                                metadata
                                sessions {
                                    id
                                    date
                                    metadata
                                }
                            }
                        }
                    }
                }
                ''',
                projectId = project_id
            )
            return data['node']['patients']


    Use the custom API in your processing script:
    To use your extended API, import the custom class into your processing script. The example below shows how to call getProjectSubjectsCustom to retrieve additional metadata for all subjects and their sessions.

    parentFolder = os.path.dirname(os.path.dirname(__file__))
    sys.path.append(parentFolder)
    from api.api import MoveshelfApiCustomized
    
    ## Setup the API
    # Load config
    personal_config = os.path.join(parent_folder, "mvshlf-config.json")
    if not os.path.isfile(personal_config):
        raise FileNotFoundError(
            f"Configuration file '{personal_config}' is missing.\n"
            "Ensure the file exists with the correct name and path."
        )
    
    with open(personal_config, "r") as config_file:
        data = json.load(config_file)
    
    # Use custom API
    api = MoveshelfApiCustomized(
            api_key_file=os.path.join(parentFolder, data["apiKeyFileName"]), 
            api_url=data["apiUrl"]
        )
    
    ## General configuration. Set values before running the script
    my_project = "<organizationName/projectName>"  # e.g. support/demoProject
    
    ## Get available projects
    projects = api.getUserProjects()
    
    ## Select the project
    project_names = [project["name"] for project in projects if len(projects) > 0]
    idx_my_project = project_names.index(my_project)
    my_project_id = projects[idx_my_project]["id"]
    
    # Custom query (defined in ../api/api.py) that extracts the metadata of all patients
    # and the metadata of all their sessions within a given project
    subjects = api.getProjectSubjectsCustom(my_project_id)
    
    # Print the subject data
    for subject in subjects:
        print(f"Subject: {subject['name']} (ID: {subject['id']})")
        print(f"Metadata: {subject['metadata']}")
        print("Sessions:")
        for session in subject['sessions']:
            print(f" - Session {session['id']} on {session['date']} with metadata: {session['metadata']}")


     

    Examples provided by Moveshelf
    To make your life easier, we have created a list of example use cases for the Moveshelf API. Each example has a dedicated section and is explained in detail later on this page.

    Refer to the following sections for example use cases for importing data:
    Refer to the following sections for example use cases for querying data:


     

    Create subject
    This section explains how to create a new subject on Moveshelf using the Moveshelf API, based on the subject's MRN/EHR-ID. Before creating a new subject, the script first checks whether a subject with the given MRN/EHR-ID already exists on Moveshelf.
    • If a matching subject is found, it is retrieved
    • If no existing subject is found, a new subject is created and assigned the specified MRN/EHR-ID
    Prerequisites
    Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:
    Implementation
    To create a new subject or retrieve an existing one, add the following lines of code to your processing script:
    ## README: this example shows how we can create a subject on Moveshelf 
    # using the Moveshelf Python API.
    # For a given project (my_project), first check if there already exists
    # a subject with a given MRN (my_subject_mrn). If it doesn't exist, 
    # we create a new subject with name my_subject_name, and assign my_subject_mrn
    
    ## General configuration. Set values before running the script
    my_project = "<organizationName/projectName>"  # e.g. support/demoProject
    my_subject_mrn = "<subjectMRN>"  # subject MRN, e.g. '1234567'
    my_subject_name = "<subjectName>"  # subject name, e.g. Subject1
    
    ## Get available projects
    projects = api.getUserProjects()
    
    ## Select the project
    project_names = [project["name"] for project in projects if len(projects) > 0]
    idx_my_project = project_names.index(my_project)
    my_project_id = projects[idx_my_project]["id"]
    
    ## Get the ID and name of all subjects in the project
    subjects = api.getProjectSubjects(my_project_id)
    
    ## Find the subject
    subject_found = False
    for subject in subjects:
        subject_details = api.getSubjectDetails(subject["id"])
        subject_metadata = json.loads(subject_details.get("metadata", "{}"))
        if my_subject_mrn == subject_metadata.get("ehr-id", None):
            subject_found = True
            print(
                f"Found subject with name: {subject_details['name']},\n"
                f"id: {subject_details['id']}, \n"
                f"and MRN: {subject_metadata.get('ehr-id', None)}"
            )
            break
    
    ## Create new subject if there is no match
    if not subject_found:
        new_subject = api.createSubject(my_project, my_subject_name)
        subject_updated = api.updateSubjectMetadataInfo(
            new_subject["id"], json.dumps({"ehr-id": my_subject_mrn})
        )        
    Validation
    To verify that the new subject has been successfully created, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project to check if the new subject appears with the correct MRN/EHR-ID. If you prefer an automated method, add the following lines of code to your processing script, right after creating the new subject, to check the subject’s details programmatically:
    # Fetch subject details using the subject ID
    new_subject_details = api.getSubjectDetails(new_subject["id"])
    new_subject_metadata = json.loads(new_subject_details.get("metadata", "{}"))
    
    # Print the subject details
    print(f"Created subject with name: {new_subject_details['name']},\n"
            f"id: {new_subject_details['id']}, \n"
            f"and MRN: {new_subject_metadata.get('ehr-id', None)}")
    This code will retrieve the newly created subject's details, including the name, ID, and MRN/EHR-ID, and print them for verification.


     

    Import subject metadata
    This example demonstrates how to import subject metadata for an existing subject on Moveshelf via the Moveshelf API. First we retrieve the subject from Moveshelf via its MRN/EHR-ID. Then, we update its subject metadata.
    Important: The keys in the metadata dictionary to be imported must match those used internally by Moveshelf. If you are unsure where to find the specific metadata template definition, please contact Moveshelf support for assistance.
    Prerequisites
    Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:
    Implementation
    To import subject metadata to an existing subject, add the following lines of code to your processing script:
    ## README: this example shows how we can import subject metadata to an existing
    # subject on Moveshelf using the Moveshelf Python API.
    # For a given project (my_project), first retrieve a subject with a given
    # MRN (my_subject_mrn). Then, update subject metadata (my_subject_metadata)
    
    ## General configuration. Set values before running the script
    my_project = "<organizationName/projectName>"  # e.g. support/demoProject
    my_subject_mrn = "<subjectMRN>"  # subject MRN, e.g. '1234567'
    my_subject_metadata = {
        "subject-first-name": "<subjectFirstName>",
        "ehr-id": my_subject_mrn,
        ... # Add all the fields you would like to import
        }  # subject metadata dictionary
    
    ## Get available projects
    projects = api.getUserProjects()
    
    ## Select the project
    project_names = [project["name"] for project in projects if len(projects) > 0]
    idx_my_project = project_names.index(my_project)
    my_project_id = projects[idx_my_project]["id"]
    
    ## Get the ID and name of all subjects in the project
    subjects = api.getProjectSubjects(my_project_id)
    
    ## Find the subject
    subject_found = False
    for subject in subjects:
        subject_details = api.getSubjectDetails(subject["id"])
        subject_metadata = json.loads(subject_details.get("metadata", "{}"))
        if my_subject_mrn == subject_metadata.get("ehr-id", None):
            subject_found = True
            # Import subject metadata
            subject_updated = api.updateSubjectMetadataInfo(
                subject["id"], json.dumps(my_subject_metadata)
            )
            break
    
    ## Print message if there was no match
    if not subject_found:
        print(
            f"Couldn't find subject MRN: {my_subject_mrn}"
        )   
    Validation
    To verify that the subject metadata has been successfully imported, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project to check if the subject appears with the correct subject metadata. If you prefer an automated method, add the following lines of code to your processing script, right after updating subject metadata, to check the subject’s metadata programmatically:
    # Fetch subject details using the subject ID
    subject_details = api.getSubjectDetails(subject["id"])
    subject_metadata = json.loads(subject_details.get("metadata", "{}"))
    
    # Print the subject details
    print(f"Created subject with name: {subject_details['name']},\n"
            f"id: {subject_details['id']}, \n"
            f"and metadata: {subject_metadata}") 
    This code will retrieve the subject's details, including the name, ID, and subject metadata, and print them for verification.


     

    Download data

    Moveshelf provides a public GitHub repository that contains several complete example scripts that are ready to be used.

    Follow the steps in this section to run an example of querying and downloading data from the Moveshelf platform, i.e., download_data.py.

    Get the public repository on your local machine

    Clone Moveshelf’s public GitHub repository to your local machine. You can do this by following these steps.

    Run download_data.py
    • Open download_data.py in Visual Studio Code, follow the instructions, add all relevant information to the script and save the file
    • To run the script, insert python scripts/download_data.py in the terminal and press 'Enter'