Navigating APIs can be difficult, especially when referencing large parameter lists or even large lists of options therein. CareQuery does its best to make the process of query building and parameter navigation as easy as possible via the helper glossary.

Access the Glossary

Every time users connect and instantiate CareQuery in python, they have access to the glossary object within their CareQuery engine.

# import
from care_query import CareQuery

# instantiate and connect
cq = CareQuery(key = "xxxxxxxxxxxxxxxxxxxxx")

# access the glossary
print(cq.glossary)

returns CareQuery glossary object...

<glossary.DataGlossary object at 0x7fc2bcf3ee80>

The CareQuery glossary has a series of functionalities that helps users find their way around the queries, tables, features, parameters and options therein.

List Query Options

If you would like to know all query options available to you within CareQuery, you may run:

# list query options
print(cq.glossary.list_queries())

which returns a list of available queries..

['careEncounter', 'careVisit', 'careEpisode', 'careJourney']

Understand Query Details

To receive full detail of a query within CareQuery, you may run the below code for any valid query:

# understand careVisit Query
print(cq.glossary.query_detail("careVisit"))

which returns a list of available queries...

`{
'description': 'Visit-based query that returns line-item level patient journey detail for healthcare visits that meet the query criterion. We define a visit as group of encounters within the same event of of care.',

'parameters': {'min_date': 'Lower threshold date within the date range of interest, observational start date',
'max_date': 'Upper threshold date within the date range of interest, observational end date',
'gender': 'Patient gender within the population of interest',
'age_min': 'Minimum patient age identified within the population of interest',
....
}`

List Query Parameters

If you would like to know all parameter options available within a CareQuery query, you may run:

# list parameters for the careJourney query
print(cq.glossary.list_parameters("careJourney"))

which returns a list of available query parameters...

`{
'min_date': 'Lower threshold date within the date range of interest, observational start date',
'max_date': 'Upper threshold date within the date range of interest, observational end date',
'gender': 'Patient gender within the population of interest',
'age_min': 'Minimum patient age identified within the population of interest',
'age_max': 'Maximum patient age identified within the population of interest',

...
'division': 'Nine distinct US State groupings as defined by the US Census Bureau',
'region': 'Four major US State groupings as defined by the US Census Bureau',
'metro': 'Metropolitan and micropolitan statistical areas according to the US Census Bureau',
'short_zip': 'First three digits the zip code of the query patient population specified',
'limit': 'Number of rows returned in the data request.',
'show': "Binary indicator as to whether you'd like your query to be printed ... on the query object itself."
}`

List Parameter Options

If you would like to better understand the description and/or underlying codes of a parameter where appropriate, run:

# list parameter options
print(cq.glossary.list_options("visit_type"))

which returns a list of available query parameter options...

['outpatient visit', 'emergency room visit', 'laboratory visit', 'home visit', 'inpatient visit', 'ambulance visit', 'non-hospital institution visit', 'pharmacy visit']

On some occasions, you may want to filter the long lists of parameter options available. The CareQuery glossary makes this easy by allowing users to filter parameter options lists by options that may contain values, such as:

# list parameter options containing cardio
cq.glossary.list_options("proc_subcategory", contains = "cardio")

which returns a filtered list of available query parameter options...

['medicine - cardiovascular', 'surgery - cardiovascular system']

Understand Parameter Hierarchy (underlying codes)

Users can also understand the codes beneath any multidimensional parameters, via:

# show region parameter hierarchy
print(cq.glossary.parameter_detail("region"))

which returns a list of available parameters options and their underlying codes...

{ 'midwest': ['MN', 'OH', 'IL', 'WI', 'KS', 'IA', 'IN', 'ND', 'SD', 'NE', 'MO', 'MI'], 'northeast': ['MA', 'ME', 'NJ', 'NH', 'RI', 'VT', 'CT', 'NY', 'PA'], 'south': ['DC', 'NC', 'MD', 'OK', 'TX', 'SC', 'WV', 'LA', ... 'KY', 'GA', 'TN', 'AL', 'MS'], 'west': ['ID', 'NM', 'NV', 'MT', 'HI', 'OR', 'WY', 'CO', 'AK', 'CA', 'UT', 'AZ', 'WA'] }

List Table Options

Though users only interact with tables insofar as the query functionalities, they can still understand what tables are available to the queries via:

# list table options
print(cq.glossary.list_tables())

which returns a list of tables...

['JOURNEY_TABLE', 'PHARMA_TABLE' ... 'PROVIDER_DETAIL_TABLE', 'AFFILIATION_TABLE']

Understand Table Details

To further understand the description of the tables, their features and the definitions of those features, you may run:

# view table details
print(cq.glossary.table_detail("JOURNEY_TABLE"))

which returns a list of tables...

{ "description": "This dataset offers comprehensive detail of longitudinal patient journeys, with line-item encounter detail, insight into payor, provider, procedure, revenue code, charges and SmartAllowedAmount\u00ae.", "queries": [ "careEncounter", "careVisit", "careEpisode", "careJourney" ], "features": { "journey_id": "Randomly generated identifier unique to each longitudinal patient journey.", "episode_id": "Randomly generated identifier unique to each sequence of encounters with at least 30 days between visits.", "visit_id": "Randomly generated identifier unique to each set of encounters that occur within the same event of care.", "encounter_id": "Randomly generated identifier, unique to an isolated event of care.", "date": "Primary date of each encounter.", "patient_age": "Age (within 5 years) of the patient on each encounter.", "patient_state": "US State residence of the patient on each encounter.", "patient_zip3": "First three zip code digits of the patient on each encounter.", "place_of_service": "Type of facility where a encounter occurred.", "visit_type": "Description of the setting of care.", "payor": "Name of the primary payor on each encounter.", "payor_channel": "Payor channel-of-business, line-of-business, or plan type.", "ref_npi": "Referring individual provider of an encounter, identified via their National Provider Identifier (NPI).", "hcp_npi": "Primary individual provider of an encounter, identified via their National Provider Identifier (NPI).", "hcp_taxonomy": "Primary taxonomy code of the individual provider on an encounter.", "hcp_specialty": "Primary specialty of the individual provider provider on an encounter.", "hco_npi": "Organizational provider of an encounter, identified via their National Provider Identifier (NPI).", "diag_1": "Primary diagnosis listed on each encounter, can be represented as an ICD10 code.", "diag_2": "Secondary diagnosis listed on each encounter, can be represented as an ICD10 code.", "diag_3": "Tertiary diagnosis listed on each encounter, can be represented as an ICD10 code.", "diag_4": "Fourth diagnosis listed on each encounter, can be represented as an ICD10 code.", "diag_5": "Fifth diagnosis listed on each encounter, can be represented as an ICD10 code.", "proc_code": "Procedure performed within each encounter.", "proc_units": "Total number of procedure units within each encounter.", "proc_modifier": "Procedure code modifier for procedure performed within encounter.", "rev_code": "Revenue Center code designated for each encounter.", "rev_units": "Total number of days in which the revenue code was designated within the healthcare interaction.", "charge": "Line-item charge submitted to insurers. The charge is the pre-adjudicated value submitted to insurers.", "smart_allowed": "Line-item estimate of allowed amount, utilizing proprietary ML on CMS, Price Transparency and Actual Adjudicated amounts to provide estimates within an average of 5% variance from actuals." } }