Searching FHIR resources with GET - AWS HealthLake
GET search examples

Searching FHIR resources with GET

You can use GET requests to search a HealthLake data store. When using GET, HealthLake supports providing search parameters as part of the URL, but not as part of a request body. For more information, see FHIR R4 search parameters for HealthLake.

Important

For searches that involve personally identifiable information (PII) or protected health information (PHI), security best practices call for using POST requests, as PII and PHI is added as part of the request body and is encrypted in transit. For more information, see Searching FHIR resources with POST.

The following procedure is followed by examples that use GET to search a HealthLake data store.

To search a HealthLake data store with GET

  1. Collect HealthLake region and datastoreId values. For more information, see Getting data store properties.

  2. Determine the type of FHIR resource to search for and collect the associated id value. For more information, see Resource types.

  3. Construct a URL for the request using the collected values for HealthLake region and datastoreId. Also include the FHIR Resource type and supported search parameters. To view the entire URL path in the following example, scroll over the Copy button.

    GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource{?[parameters]{&_format=[mime-type]}}

  4. Send the GET request with either AWS Signature Version 4 or SMART on FHIR authorization. The following curl example returns the total number of Patient resources in a HealthLake data store. To view the entire example, scroll over the Copy button.

    curl

    SigV4 authorization

    curl --request GET \
  'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_total=accurate \   
  --aws-sigv4 'aws:amz:region:healthlake' \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  --header "x-amz-security-token:$AWS_SESSION_TOKEN" \                          
  --header 'Accept: application/json'
    AWS Console
    Note

    The HealthLake Console supports only SigV4 authorization. SMART on FHIR authorization is supported through AWS CLI and AWS SDKs.

    1. Sign in to the Run query page on the HealthLake Console.

    2. Under the Query settings section, make the following selections.

    • Data Store ID — choose a data store ID to generate a query string.

    • Query type — choose Search with GET.

    • Resource type — choose the FHIR resource type to search on.

    • Search parameters — Select a search parameter or combination of search parameters to focus your query on specific records.

    3. Choose Run query.

Examples: search with GET

The following tabs provide examples for searching on specific FHIR resource types with GET. The examples show how to specify search parameters in the request URLs.

Note

The HealthLake Console supports only SigV4 authorization. SMART on FHIR authorization is supported through AWS CLI and AWS SDKs.

HealthLake supports a subset of FHIR R4 search parameters. For more information, see Search parameters.

Patient (age)

Although age is not a defined resource type in FHIR, it is captured as an element in the Patient resource type. Use the following example to make a GET-based search request on Patient resource types using the birthDate element and the eq search comparator to search for individuals born in the year 1997.

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?birthdate=eq1997
Condition

Use the following example to make a GET request on the Condition resource type. The search finds conditions in your HealthLake data store that contain the SNOMED medical code 72892002, which translates to Normal pregnancy.

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Condition?code=72892002
DocumentationReference

The following example shows how to create a GET request on the DocumentReference resource type for Patient(s) with a streptococcal diagnosis and who have also been prescribed amoxicillin.

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/DocumentReference?_lastUpdated=le2021-12-19&infer-icd10cm-entity-text-concept-score;=streptococcal|0.6&infer-rxnorm-entity-text-concept-score=Amoxicillin|0.8
Location

Use the following example to make a GET request on the Location resource type. The following search finds locations in your HealthLake data store that contain the city name Boston as part of the address.

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Location?address=boston
Observation

Use the following example to make a GET-based search request on the Observation resource type. This search uses the value-concept search parameter to look for medical code 266919005, which translates to Never smoker.

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Observation?value-concept=266919005