Search with POST examples - AWS HealthLake

Search with POST examples

You can search a HealthLake data store by making POST requests. You can provide query parameters in either the URI or in a request body, but you cannot use both in a single request.

The examples in this topic follow that best practice.

Note

For queries that involve Personally identifiable information (PII) or Protected Health Information (PHI) it's recommended to use POST requests. In a POST request, PII or PHI is added as part of the request body and is encrypted in transit.

When making a POST request with a parameter in the request body, use Content-Type: application/x-www-form-urlencoded as part of the header.

This topic provides you with examples of how to search with POST by using the following resource types.

  • Age: Age is not a defined resource type in FHIR. Instead, age is captured as a part of the Patient resource type. To search for a group of patients based on specific age or age range, use a Supported search comparators. For more details, see Resource type: Patient in the FHIR Documentation Index.

  • Condition: This resource type stores details related to clinical concepts such as a diagnosis, situations, a clinical condition, and problems that have risen to a level of concern. To learn more, see Resource type: Condition in the FHIR Documentation Index. HealthLake creates new conditions based on documents found in the DocumentReference. These additions are excluded by default when making a POST request. To include them, you must specify a valid identifier for a condition resource in your search.

  • DocumentReference:This resource type is supported by HealthLake. This resource type supports referencing documents of any type. To learn more, see Resource type: DocumentReference in the FHIR Documentation Index. HealthLake also provides integrated natural language processing (NLP) of documents found in the DocumentReference. To learn more, see Using automated resource generation based on natural language processing (NLP) of the FHIR DocumentReference resource type in AWS HealthLake.

  • Location: This resource type includes both incidental locations (a place that is used for healthcare without prior designation or authorization) and dedicated, formally appointed locations. For more details, see Resource type: Location in the FHIR Documentation Index.

  • Observation: Measurements and simple assertions made about a patient, device, or other subject. HealthLake creates new observation resources based on documents found in the DocumentReference resource. To learn more about how HealthLake creates new resources, see Using automated resource generation based on natural language processing (NLP) of the FHIR DocumentReference resource type in AWS HealthLake. These additions are excluded by default when making a POST request. To include them, you must specify a valid identifier for an observation resource in your search. To learn more, see Resource type: Observation in the FHIR Documentation Index.

Each tab shows examples of how to search on the specified resource type. It includes an example of how to specify the request in the request body.

Age

Use the following to make a POST-based search request on the Patient resource type. This search uses the eq search comparator to search for individuals who were born in 1997.

You have to specify a request URL and a request body. Here is an example request URL.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient/_search

To specify the year 1997 in the search, you would add the following element to the request body.

birthdate=eq1997
JSON Response

When successful, you will get a 200 HTTP response code and a similar JSON response.

Condition

Using the following to make a POST request on the Condition resource type. This search finds locations in your HealthLake data store that contain the medical code 72892002.

You have to specify a request URL and a request body. Here is an example request URL.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Condition/_search

To specify the medical code you want to search, you add this JSON element to the request body.

code=72892002
JSON Response

When successful, you will get a 200 HTTP response code. The following JSON response has been truncated for clarity.

{
	"resourceType": "Bundle",
	"type": "searchset",
	"entry": [{
			"resource": {
				"resourceType": "Condition",
				"id": "0063326c-6b42-4d13-af2f-1efe0a65f016",
				"meta": {
					"lastUpdated": "2022-08-23T00:22:49.681Z"
				},
				"clinicalStatus": {
					"coding": [{
						"system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
						"code": "resolved"
					}]
				},
				"verificationStatus": {
					"coding": [{
						"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
						"code": "confirmed"
					}]
				},
				"code": {
					"coding": [{
						"system": "http://snomed.info/sct",
						"code": "72892002",
						"display": "Normal pregnancy"
					}],
					"text": "Normal pregnancy"
				},
				"subject": {
					"reference": "Patient/5fc0070a-696a-4855-94a9-175f1c641a33"
				},
				"encounter": {
					"reference": "Encounter/44078ab9-7ac7-4731-9ac8-4b3ff21a7bdb"
				},
				"onsetDateTime": "2019-08-15T01:19:17-07:00",
				"abatementDateTime": "2020-03-26T01:19:17-07:00",
				"recordedDate": "2019-08-15T01:19:17-07:00"
			},
			"search": {
				"mode": "match"
			}
		},
		{
			"resource": {
				"resourceType": "Condition",
				"id": "d00afdb2-1d2c-44fe-9f3b-033c0fe751a3",
				"meta": {
					"lastUpdated": "2022-08-23T00:20:47.100Z"
				},
				"clinicalStatus": {
					"coding": [{
						"system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
						"code": "resolved"
					}]
				},
				"verificationStatus": {
					"coding": [{
						"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
						"code": "confirmed"
					}]
				},
				"code": {
					"coding": [{
						"system": "http://snomed.info/sct",
						"code": "72892002",
						"display": "Normal pregnancy"
					}],
					"text": "Normal pregnancy"
				},
				"subject": {
					"reference": "Patient/d0a5cd1e-8da7-41bd-9b2f-41eef45246e5"
				},
				"encounter": {
					"reference": "Encounter/73758e67-4aaf-4e80-982b-8821f0b6fdfb"
				},
				"onsetDateTime": "2019-06-13T20:37:40-07:00",
				"abatementDateTime": "2020-01-23T19:37:40-08:00",
				"recordedDate": "2019-06-13T20:37:40-07:00"
			},
			"search": {
				"mode": "match"
			}
		}
	]
}
DocumentReference

To see the results of HealthLake's integrated natural language processing (NLP) when making a POST request on the DocumentReference resource type, format a request is as follows.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/DocumentReference/_search

To specify the DocumentReference element you want to reference, see Search parameters. You'll specify those in the request body as JSON.

_lastUpdated=le2021-12-19&infer-icd10cm-entity-text-concept-score;=streptococcal|0.6&infer-rxnorm-entity-text-concept-score=Amoxicillin|0.8

This query string uses multiple search parameters to search on Amazon Comprehend Medical API operations used to generate the integrated medical NLP results.

Location

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

You must specify a request URL and a request body. Here is an example request URL.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Location/_search

To specify Boston in the search, add the following element to the request body:

address=Boston
JSON Response

When successful, you will get a 200 HTTP response code. The JSON response has been truncated for clarity.

{
	"resourceType": "Bundle",
	"type": "searchset",
	"entry": [{
			"resource": {
				"resourceType": "Location",
				"id": "0a6903c7-25c5-4ae4-8354-be88f9c5f2ee",
				"meta": {
					"lastUpdated": "2022-08-23T00:24:24.570Z"
				},
				"status": "active",
				"name": "BRIGHAM AND WOMEN'S HOSPITAL",
				"telecom": [{
					"system": "phone",
					"value": "6177325500"
				}],
				"address": {
					"line": [
						"75 FRANCIS STREET"
					],
					"city": "BOSTON",
					"state": "MA",
					"postalCode": "02115",
					"country": "US"
				},
				"position": {
					"longitude": -71.020173,
					"latitude": 42.33196
				},
				"managingOrganization": {
					"reference": "Organization/27379046-608b-32f0-9df7-8c833cf5d11d",
					"display": "BRIGHAM AND WOMEN'S HOSPITAL"
				}
			},
			"search": {
				"mode": "match"
			}
		},

		{
			"resource": {
				"resourceType": "Location",
				"id": "ca5e7f65-4eb5-4bff-9a6f-07bc80acf8d0",
				"meta": {
					"lastUpdated": "2022-08-23T00:20:47.100Z"
				},
				"status": "active",
				"name": "BETH ISRAEL DEACONESS MEDICAL CENTER",
				"telecom": [{
					"system": "phone",
					"value": "6176677000"
				}],
				"address": {
					"line": [
						"330 BROOKLINE AVENUE"
					],
					"city": "BOSTON",
					"state": "MA",
					"postalCode": "02215",
					"country": "US"
				},
				"position": {
					"longitude": -71.020173,
					"latitude": 42.33196
				},
				"managingOrganization": {
					"reference": "Organization/cb6a50e0-af76-3758-99ad-3200ede03fff",
					"display": "BETH ISRAEL DEACONESS MEDICAL CENTER"
				}
			},
			"search": {
				"mode": "match"
			}
		}
	]
}
Observation

Using the following to make a POST-based search request on the Observation resource type. This search uses the value-concept search parameter to look for medical code, 266919005. This status indicates Never smoker.

You have to specify a request URL and a request body. Here is an example request URL.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Observation/_search

To specify the status, Never smoker , set value-concept=266919005 in the body of the JSON.

value-concept=266919005
JSON Response

When successful, you will get a 200 HTTP response code. The following JSON response has been truncated for clarity.

{
	"resourceType": "Bundle",
	"type": "searchset",
	"link": [{
		"relation": "next",
		"url": "https://healthlake.us-west-2.amazonaws.com/datastore/3651c6d3c1e81e785adba06b710b52a9/r4/Observation?value-concept=266919005&=AAMA-EFRSURBSGlpcGIyN250ZG9WRXVnTTFOdmtxQk9Bb3Y0YjhVcVdUMGV0eVozNmdjQU9nRjRNUUtscjhCZ1NMUG84VGNqN09nNEFBQUFmakI4QmdrcWhraUc5dzBCQndhZ2J6QnRBZ0VBTUdnR0NTcUdTSWIzRFFFSEFUQWVCZ2xnaGtnQlpRTUVBUzR3RVFRTXI1VWxTbC9lZksydlVkMlpBZ0VRZ0R2bnF6cFFtQzBPdDBXaE82ZWhqbW92QndlcmVkVVBrbU40cnlsWGI1VWJJVWdxVDhUZkxqS3dHSHZOQUNZWkVsajZsa05FNzV6R1dtZnhSZz09tEeRZ6lNDlYyIdmiLObGMU7YIThPsFO5z9gTfXONPrm7i8GdXQgsbBjgMu2BrOFUdPhGOf4Ly8aBOGcCjN60es9nGG27XzRk_3_CkaVjEFZFlbwmPvWM6RXGKdbyExLlR3yOdIFQscvlT1iKj5DlHHLQDanYppTopxDRpTsiy8MozsqK0ENS0NLViqJsCCSmGOxuTZYllB5dckwimpQKfesMxmc_LKEmsjc="
	}],
	"entry": [{
			"resource": {
				"resourceType": "Observation",
				"id": "000038e0-71c6-4cc0-9c6c-50c8b1c53309",
				"meta": {
					"lastUpdated": "2022-11-03T01:02:38.981Z"
				},
				"status": "final",
				"category": [{
					"coding": [{
						"system": "http://terminology.hl7.org/CodeSystem/observation-category",
						"code": "survey",
						"display": "survey"
					}]
				}],
				"code": {
					"coding": [{
						"system": "http://loinc.org",
						"code": "72166-2",
						"display": "Tobacco smoking status NHIS"
					}],
					"text": "Tobacco smoking status NHIS"
				},
				"subject": {
					"reference": "Patient/598c9d7a-0494-448e-a81e-d50e3606e8db"
				},
				"encounter": {
					"reference": "Encounter/86bdee4a-2aa9-474a-b43f-6237cd68e512"
				},
				"effectiveDateTime": "2019-12-11T19:44:57-08:00",
				"issued": "2019-12-11T19:44:57.438-08:00",
				"valueCodeableConcept": {
					"coding": [{
						"system": "http://snomed.info/sct",
						"code": "266919005",
						"display": "Never smoker"
					}],
					"text": "Never smoker"
				}
			},
			"search": {
				"mode": "match"
			}
		},

		{
			"resource": {
				"resourceType": "Observation",
				"id": "0c2f6260-e671-4cfd-ac3d-e75f073fa3cd",
				"meta": {
					"lastUpdated": "2022-11-03T01:05:21.488Z"
				},
				"status": "final",
				"category": [{
					"coding": [{
						"system": "http://terminology.hl7.org/CodeSystem/observation-category",
						"code": "survey",
						"display": "survey"
					}]
				}],
				"code": {
					"coding": [{
						"system": "http://loinc.org",
						"code": "72166-2",
						"display": "Tobacco smoking status NHIS"
					}],
					"text": "Tobacco smoking status NHIS"
				},
				"subject": {
					"reference": "Patient/89d9a9b7-9720-4881-a2ab-d7907544b26f"
				},
				"encounter": {
					"reference": "Encounter/8ebba7b0-fdfc-4ec1-a9aa-907cccf60925"
				},
				"effectiveDateTime": "2018-11-17T03:59:36-08:00",
				"issued": "2018-11-17T03:59:36.550-08:00",
				"valueCodeableConcept": {
					"coding": [{
						"system": "http://snomed.info/sct",
						"code": "266919005",
						"display": "Never smoker"
					}],
					"text": "Never smoker"
				}
			},
			"search": {
				"mode": "match"
			}
		}
	]
}