Profiles & Operations > Operation: Search Location
Search Location
Location search is simple RESTful interactions. It supports retrieving a single Location instance by Location Identifiers, as well as other search criteria.
Scope
This transaction involves a request by the following Identifiers for:
Location
| Source | Identifier |
|---|---|
| Ministry of Health URI | Stakeholder Number |
| Unique Provider Identifier URI | UPI |
| Ontario College of Pharmacist Organization URI (https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-license-pharmacist-org) | Org ID(eg. Accreditation number for Pharmacies) |
| College of Midwives Organization URI (https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-license-midwife-org) | Org ID |
Any search must include the identifier and source URI. All searches, by identifier, against PPR must be qualified with the Issuer code. Issuers are identified by the appropriate URI value. Identifiers are sequential/random numeric values issued by each source. As such, there may be overlap of identifier values across sources.
An FHIR RESTful client sends the search by identified types of Location identifiers; the request is received by the FHIR Practitioner RESTful Server which returns the requested resource. This transaction requires the use and knowledge of specific types of identifiers.
Any Location Definitional Identifier may be used with this interaction; a Definitional identifier is one that is a Unique Identifier assigned by a source of information to the PPR. This type of identifier includes a Ministry of Health assigned Stakeholder number, License number issued by a Regulatory college, or a UPI (Unique Provider Identifier) as assigned by the former Legacy Provider Registry and ported to PPR. In any case, the search identifier parameter must be specified along with the correct URI value assigned to the identifier issuer.
The client must provide the correct value of the identifiers as specified above, either from the Practitioner EHR record, public record or from the result of another FHIR transaction (e.g. Practitioner/Location Match). For example, a Pharmacist may use the search operation to retrieve the Prescriber (Practitioner) information from the registry using Practitioner’s UPI from Practitioner’s EHR record, or the Practitioner’s regulatory college issued license number.
In addition the searching by identifier, this operation also supports search using the following search criteria:
| Query Search Parameters | Type | Description | Usage Note |
|---|---|---|---|
| name (Location.name) |
string | ||
| type (Location.type.coding) |
token | The Location type | |
| telecom (Location.telecom) |
token | By combined telecom type (e.g. phone, email) with telecom value (e.g. phone number, email address) | |
| address Location.address |
string | A (part of the) address of the location | |
| lhin Location.extension:LHIN-code |
token | The numeric LHIN code for this location | |
| registration-subclass Location.extension:registration-subclass |
The location's registration subclass as per the extension binding | ||
| organizaton-type Location.extension:organization-type |
token | The location's managing organization's org type, as per the extension binding. |
Interaction Diagrams
The following diagram illustrates the high level interaction between a FHIR Client and FHIR Provider RESTful Server. In this implementation guide, Provincial Provider Registry is playing the role of the FHIR Provider RESTful Server. All subsequent references of this actor (FHIR Provider RESTful server) should be interpreted as the Provincial Provider Registry.
The Provider FHIR transaction will use the following query and response:
• Location Search Request /Location Search Response
Actor: FHIR Provider RESTful Client
Role: Requestor
Requests a detailed profile of a single Location based on a known Location ID Issuer from the FHIR Provider RESTful Server. The FHIR Client uses the information received from the FHIR Provider RESTful Server for its own purposes. The RESTful client is referred to as the “FHIR client” in the remainder of the document.
Actor: FHIR Provider RESTful Server
Role: Information Service
Returns a bundle containing the demographic information for the single Location corresponding to the Issuer & ID values specified by the FHIR Provider RESTful Client. This actor is referred to as the FHIR server in the remainder of the document.
Specification
This FHIR Provider specification is based on the HL7 R4 Search operation. It makes use of the following resources:
Provider Location Search Request
The Location Search Request can be done by using an HTTP POST operation(alternatively, clients can also send GET based search ) with exactly one query parameter specified below. The syntax of the request is always
POST [base]/Location/_search?identifier=[system]|[value]
Or alternatively,
GET [base]/Location?identifier=[system]|[value]
Note: For list of Identifiers ,see scope section above
Provider Location search Response
General
The PHSD FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR R4 does not support all the data elements required for this project, we have introduced a few extensions which can be found here.
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 PHSD, the server will also return the Practitioner, PractitonerRole, Location, and Organization resources that are associated to the Location 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").
Extensions
Summary of Supported Operations
The table below shows the allowed transactions for each profile and how they support FHIR endpoints, resources and their corresponding HTTP operations:
| Resource | Transaction | HTTP Operations | URL | Request Body Resource | Response Body Resource |
|---|---|---|---|---|---|
| Location | Search | POST | [base]/Location/_search? | N/A | Bundle containing Location |
Alternatively, clients can also send GET based search as follows:
| Resource | Transaction | HTTP Operations | URL | Request Body Resource | Response Body Resource |
|---|---|---|---|---|---|
| Location | Search | GET | [base]/Location? | N/A | Bundle containing Location |
The interaction summary table below lists the HTTP status codes that may be returned for the search.
| Interaction | Content-Type | Body | Location | Versioning | Status Codes | Comments |
|---|---|---|---|---|---|---|
| Search (Location) | R | R: Bundle | N/A | N/A | 200,400,404,422,500 |
Location Search Operations
The Location search is invoked through a HTTP POST (alternatively HTTP GET) specifying the issuer (e.g. URI of PPR EPID, CPSO etc.) and identifier value (EPID, UPI, etc.) of a single Location instance. The response from the FHIR Provider RESTful Server will be a Location Resource, or in the case of a failed search, an operation outcome resource.
Trigger Event
When a FHIR Client has the identifiers for an Location but does not yet have the name, contact, license and other information or wishes to retrieve an updated version of the Location's information, it invokes an Location search.
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 Location resource matching the specified search criteria is found | HTTP 200 | OK. Returns a search result Bundle containing Location resources that match the search criteria. | |||
| 200 OK | No Location 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 |
Examples
Location search requests :
POST [base]/Location/_search?identifier=[system]|[value]
Or alternatively,
GET [base]/Location?identifier=[system]|[value]
**Examples of Location search request can be found below **
POST [base]/Location/_search?identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-license-pharmacist-org|12324566
Or alternatively,
GET [base]/Location?identifier= https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-provider-upi|3456789023
GET [base]/Location?identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-license-pharmacist-org|12324566
Location search response:
Examples of a Location Search Response(bundle) for Search by Identifier can be found below
Example of Operation Outcome