Make an API Call (Python SDK)

Initialize the API, submit a request, and examine the response.

Step 1: Initialize the ScienceIO Client

To initialize the request, make sure you import the ScienceIO library and create a scio object:

from scienceio import ScienceIO
scio = ScienceIO()

You must use Python v3.7 or above.

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 the query_text, identify all healthcare concepts, and return the results (print(response)) in JSON.

Click here to learn how to call a different endpoint.

# 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)

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 (exception: 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.

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.

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

For more information about each key:value pair in the JSON response (shown below), see JSON Schema: 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 the Response (Optional)

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

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. Here are two additional code examples that can be used after you load your JSON response to a DataFrame.

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:

Click here to learn more about using pandas.