Query with curl¶

Quick Start¶

Install the jq json formatter tool if you don't have it already¶

!apt-get install -yq jq > /dev/null
!jq --version

Set the FHIR-Aggregator address to a variable¶

%env FHIR_BASE= https://google-fhir.fhir-aggregator.org

Run any standard FHIR query¶

This example query returns the official identifier for all ResearchStudy resources:

! curl -s $FHIR_BASE'/ResearchStudy?_elements=identifier&identifier.use=official' | jq -rc '.entry[] | [ (.resource.identifier[] | .value), .fullUrl]' | sort

• $FHIR_BASE is the environment variable we set earlier, which holds the FHIR server's base URL. It's expanded to the actual URL during execution.
• /ResearchStudy is the FHIR resource type we are interested in (in this case, "ResearchStudy").
• ?_elements=identifier is a FHIR search parameter that limits the returned data to only include the 'identifier' element of the ResearchStudy resources.

Example: query the FHIR server and load the results into a Pandas DataFrame.¶

import requests
import pandas as pd
import json

# Assuming FHIR_BASE is already set as an environment variable. If not, set it here like fhir_base_url = 'https://google-fhir.fhir-aggregator.org'
fhir_base_url = %env FHIR_BASE

# Define the API endpoint
endpoint = f"{fhir_base_url}/ResearchStudy?_elements=identifier&identifier.use=official"

# Make the request
response = requests.get(endpoint)

# Check for successful response
if response.status_code == 200:
    # Parse the JSON response
    data = response.json()

    # Extract identifiers
    identifiers = []
    for entry in data.get('entry', []):
        resource = entry.get('resource', {})
        for identifier in resource.get('identifier', []):
            # add the url RearchStudy to the dataframe
            identifier['url'] = entry.get('fullUrl')
            identifiers.append(identifier)

    # Create a Pandas DataFrame
    print(f"Found {len(identifiers)} ResearchStudy identifiers. Use the 'url' field to retrieve the data.")
    df = pd.DataFrame(identifiers)
    display(df)  # Display the DataFrame
else:
    print(f"Error: Request failed with status code {response.status_code}")

Full Documentation¶

Install jq json¶

jq: Your JSON Navigator¶

The jq utility is a lightweight and flexible command-line JSON processor. It's like a Swiss Army knife for working with JSON data, and it is used here to help organize the responses from the FHIR server in a readable way.

!apt-get install -yq jq > /dev/null
!jq --version

Specify the endpoint¶

• We need to select the FHIR Server's URL https://google-fhir.fhir-aggregator.org

Set the FHIR-Aggregator address to a variable¶

In [2]:

%env FHIR_BASE= https://google-fhir.fhir-aggregator.org

%env FHIR_BASE= https://google-fhir.fhir-aggregator.org

env: FHIR_BASE=https://google-fhir.fhir-aggregator.org

• This line of code tells the notebook, "Remember this address: https://google-fhir.fhir-aggregator.org, and label it FHIR_BASE. We'll use it later to talk to a server that stores healthcare data."

• By setting this environment variable, the URL to the FHIR Aggregator server is conveniently stored for later use within the notebook. This way you won't need to repeat the URL every time it's needed.

• From there we have access to search the data in the server using FHIR queries

Vocabulary Dataframe¶

As a convenience, the fhir-aggregator-client's vocabulary command will query this data and save it in a local dataframe.

This generates a tab-separated file named vocabulary.tsv, which serves as an inventory of the server's data elements and their usage, including example FHIR queries to retrieve those values.

In [3]:

%%capture [--no-stdout]

!fq vocabulary vocabulary.tsv --fhir-base-url $FHIR_BASE

%%capture [--no-stdout] !fq vocabulary vocabulary.tsv --fhir-base-url $FHIR_BASE

Lets visualize the dataframe to browse all available search parameters

In [4]:

import pandas as pd
df = pd.read_csv('vocabulary.tsv', sep='\t').fillna('')
df

import pandas as pd df = pd.read_csv('vocabulary.tsv', sep='\t').fillna('') df

Out[4]:

Loading ITables v2.5.2 from the init_notebook_mode cell... (need help?)

Or, if you know the study you are interested in, you can use standard python or pandas dataframe operations to look at relevant subsets. Here are all of the values available in FHIR Aggregator for GTEX version 10

In [5]:

df.loc[df['research_study_identifiers'] == 'GTEX_V10']

df.loc[df['research_study_identifiers'] == 'GTEX_V10']

Out[5]:

Loading ITables v2.5.2 from the init_notebook_mode cell... (need help?)