Profiles & Operations > Operation: Search HealthcareService
Search HealthcareService
The Search HealthcareService Restful operation issues a parameterized query that results in a searchset Bundle that contains all HealthcareService resources that match the search parameters, with additional related FHIR resources referencing and referenced by those matching HealthcareService resources. This operation supports retrieval of a set of instances using the following search criteria:
| Query Search Parameters | Type | Description | Usage Note |
|---|---|---|---|
| active (HealthcareService.active) |
token | The Healthcare Service is currently marked as active. | active=true or active=false |
| identifier (HealthcareService.identifier) |
token | Busines identifiers of the healthcare service | identifier system and value must be provided |
| name (HealthcareService.name) |
string | A portion of the Healthcare service name | Any Healthcare Service with a name containing a given part with the provided string at the start of the name. The query can also use ":contains" to search for any name that contains the provided string |
| characteristic (HealthcareService.characteristic) |
token | One of the HealthcareService's characteristics | For example: search for healthcareserivce that is “wheelchair accessible”. Since PHSD only supports text, ":text" should be used e.g. characteristic:text="wheelchair accessible" |
| program (HealthcareService.program) |
token | For PHSD the valueset consists of eServices | eConsult | eVisit | Connex | THLN | THRS | TH811. | |
| service-category (HealthcareService.category) |
token | The service category is used to determine the available service types available within a program. | |
| service-type (HealthcareService.type) |
token | The available service types will be different for each program and category. See the respective ValueSets for each slice in the HealthcareService profile. | |
| specialty (HealthcareService.specialty) |
token | Used to search specialties and subspecialties available at this healthcare service. For eConsult, the specialty field is used to capture both specialties and subspecialties. | |
| coverage-area (HealthcareService.coverageArea) |
reference(Location) | Used to search against a LHIN | Name search [baseURL]/HealthcareService?coverageArea.name:contains=LHIN or [baseURL]/HealthcareService?coverageArea.name:exact=LHIN7 |
| location (HealthcareService.location) |
reference | The location of the Healthcare Service | GeoCode search [baseURL]/HealthcareService?location.near=[latitude]|[longitude]|[distance]|[unit], where distance & unit are optional. If the units are omitted, then kms should be assumed. |
| organization (HealthcareService.providedBy) |
reference | The organization that provides this Healthcare Service | |
| _count | integer | The count parameter returns the results of search in a series of pages. This parameter instructs the server on how many resources are to be returned in a single page. |
Specification
This FHIR Search HealthcareService operation is based on the HL7 R4 Restful Search operation.
HealthcareService Search Request
The HealthareService Search Request is an HTTP GET or POST operation. The syntax of the request is as follows:
POST [base]/HealthcareService/_search (with parameters passed in the HTTP Body)
Or alternatively,
GET [base]/HealthcareService?param1=value1¶m2=value2%...
HealthcareService Search Response
The HealthcareService Search operation will return a FHIR Bundle (Bundle.type = searchset), containing the the search result entries for for HealthcareService FHIR resources, and supplementary entries for related information for Practitioner, PractitionerRole, Location, and Organization. See the "Search Mode" section below on how to distinguish between search result entires versus supplementary entries.
General
Search.Mode
The base FHIR specification states that while Search must return the requested resource type, HealthcareService, the server may also choose to return additional relevant resources. In the case of PHPD, the server will also return the Practitioner, PractitonerRole, Location, and Organization resources that are associated to the HealthcareService search results.
The element Bundle.entry[x].search.mode will be used to distinguish between which resources are being returned as a direct result of the search (value="match") vs inclusion for relevance (value="include"). Similarly, this may also be used to indicate OperationOutcome resources that were included (value="outcome").
Example Search Queries
Search by program and category
[base]/HealthcareService?program=THLN&service-category=M13
Search by program and type
[base]/HealthcareService?program=Connex&service-type=http://ehealthontario.ca/fhir/CodeSystem/service-type-connex|mental%20health
Expected Behavior
See Response Handling page for additional response handling behaviour.
| Legend |
|---|
| code = OperationOutcome.issue.code |
| severity = OperationOutcome.issue.severity |
| details.coding.code=OperationOutcome.issue.details.coding.code |
| details.coding.display=OperationOutcome.issue.details.coding.display |
| details.text = OperationOutcome.issue.details.coding.text |
| HTTP Status | Scenario Description | severity | code | details.coding.code | details.coding.display | details.text |
|---|---|---|---|---|---|---|
| 200 OK | At least one HealthcareService matching the specified search criteria is found | HTTP 200 | OK. Returns a search result Bundle containing HealthcareService resources that match the search criteria. | |||
| 200 OK | No HealthcareService resources matching the specified search criteria are found. Returns an search result Bundle with zero search results. Also returns an OperationOutcome resource with a warning indicating no summaries were found. | warning | not-found | |||
| 400 Bad Request | Missing security token | error | required | Missing required security token: PIN | ||
| 400 Bad Request | POST operation contains incorrect header value for "Content-Type" - should be "application/fhir+json" | error | invalid | |||
| 400 Bad Request | When there was syntactical error such as a missing or invalid header, a missing or invalid URL parameter, a request body that can't be parsed or doesn't conform to the basic FHIR JSON/XML syntax rules, etc. Returns an OperationOutcome resource indicating an issue. The client must fix the request and try again. | error | invalid | Will vary depending on the error | ||
| 401 Unauthorized | Failed authentication | error | security | Authorization is required for the interaction that was attempted | ||
| 406 Not Acceptable | The Accept header requested a format that the server does not support | error | not-supported | |||
| 422 Unprocessible Entity | FHIR validation errors such as invalid code, wrong date format, or violation of LOB defined business rules | Will vary depending on the error | Will vary depending on the error | OH-defined error code | OH-defined errror message | |
| 429 Too Many Requests | Rate Limit | error | throttled | Too Many Requests | ||
| 500 Internal Server Error | PHSD API validates the request but cannot return a valid response due to internal issues. | fatal | exception | Internal Error | ||
| 503 Service Unavailable | Indicates that the services has been temporarily taken down (on purpose) | |||||
| 504 Gateway Timeout | Downstream system(s) did not return timely response | error | timeout |
Healthcare Service search response:
Examples of a Healthcare Service Search Response(bundle) for Search by Identifier can be found below
Example of Operation Outcome