Make an API Call (Python SDK)

❗️

Important

Make sure you have gotten your API keys and configured your environment before trying to submit an API request.

Step 1: Initialize the ScienceIO Client

To initialize the request, import the ScienceIO library and create a scio object. Make sure you are using Python v3.7 or above:

from scienceio import ScienceIO

scio = ScienceIO()

📘

If you are getting a ModuleNotFoundError, make sure you have installed the scienceio Python Package within the tool and/or notebook you are using. You may do this via the UI of some editors by searching for and adding the scienceio package, or by using the pip install scienceio command within the notebook.

Step 2: Submit the Request

All requests must be submitted using text.

Use the scio.structure() method to submit a request to the structure endpoint, which will ask the API to examine query_text, identify all healthcare concepts, and return the results (print(response)) in JSON.

Note that your API keys will be passed to the API automatically because they were asked for when configuring your environment and/or running a query for the first time. You do not need to manually pass them in your code (however if you call the API again in a new Jupyter notebook, you may be asked to re-input your keys). You can find or edit your keys in ~/.scienceio/config.

# Replace the text with your query text. Single or double quotes are permitted.

query_text = "ALS is often called Lou Gehrig's disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs."

response = scio.structure(query_text)

print(response)

Click here to learn how to call a different endpoint.

Step 3: Examine the API Response

The response from the API is in JSON, and includes a number of key:value pairs that hold the pieces of healthcare information found in the query_text. If you are working in a Jupyter notebook, you can add the following code to make the results easier to read (like the example JSON message below):

import json
print(json.dumps(response, indent=2))

For more information about each key:value pair, see Structure.

{
  "text": "ALS is often called Lou Gehrig's disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs.",
  "spans": [
    {
      "concept_id": "UMLS:C0002736",
      "concept_name": "Amyotrophic Lateral Sclerosis",
      "concept_type": "Medical Conditions",
      "pos_end": 3,
      "pos_start": 0,
      "score_id": 0.9997076392173767,
      "score_type": 0.999858021736145,
      "text": "ALS"
    },
    {
      "concept_id": "UMLS:C0002736",
      "concept_name": "Amyotrophic Lateral Sclerosis",
      "concept_type": "Medical Conditions",
      "pos_end": 40,
      "pos_start": 20,
      "score_id": 0.6796196103096008,
      "score_type": 0.9957892298698425,
      "text": "Lou Gehrig's disease"
    },
    {
      "concept_id": "UMLS:C0004795",
      "concept_name": "Baseball Game",
      "concept_type": "Context",
      "pos_end": 60,
      "pos_start": 52,
      "score_id": 0.9998717308044434,
      "score_type": 0.9998181462287903,
      "text": "baseball"
    },
    {
      "concept_id": "UMLS:C0031831",
      "concept_name": "Physicians",
      "concept_type": "Context",
      "pos_end": 102,
      "pos_start": 95,
      "score_id": 0.9998661279678345,
      "score_type": 0.9999226331710815,
      "text": "Doctors"
    },
    {
      "concept_id": "UMLS:C0002736",
      "concept_name": "Amyotrophic Lateral Sclerosis",
      "concept_type": "Medical Conditions",
      "pos_end": 130,
      "pos_start": 127,
      "score_id": 0.9996334314346313,
      "score_type": 0.999842643737793,
      "text": "ALS"
    }
  ]
}

Step 4: Use Pandas to Explore Results (Optional)

You can perform further analysis of the JSON response by using pandas to create a DataFrame. We recommend using pandas to get the most out of your data.

📘

There are a number of ways to use a pandas DataFrame, based on how you wish to examine or filter the JSON response. See Analytics with Pandas for more information.

1. Import Package and Create a DataFrame

First, import pandas under the pd alias, and load your JSON response to a DataFrame using the json_normalize operation.

# Import required package
import pandas as pd

# Load JSON response to df
df = pd.json_normalize(response['spans'])
df.head()

The result looks like this:

2. Decide How to Explore

Next, decide how you want to filter your results. We have included two examples below.

📘

Remember, these two examples are not the only ways to explore results using a pandas DataFrame. You may try one or both of these code snippets.

Example 1: Filter results to only include medical conditions:

# Subset the df to only medical conditions
filtered_results = df[df["concept_type"]=="Medical Conditions"]
filtered_results

The result looks like this:

Example 2: Create a count of each unique medical condition:

# Create a count of each unique medical condition
filtered_results["concept_name"].value_counts()

The result looks like this:

Learn more about using pandas.