This page is part of the FHIR Specification (v3.0.2: STU 3). The current version which supercedes this version is 5.0.0 . For a full list Continuous Integration Build of available versions, see FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Content
• Examples Detailed Descriptions
• Detailed Descriptions Search Params
• Mappings
• Examples
• Operations
• Profiles & Extensions
• R2 Conversions Extensions

8.7 Resource Location - Content

Responsible Owner: Patient Administration Work Group

Normative Maturity Level : 3

Trial Use Security Category : Business

Compartments : Not linked to any No defined compartments

Details and position information for a physical place where services are provided and resources and participants may be stored, found, contained contained, or accommodated.

This resource is referenced by

8.7.3 References to this Resource

• Implements: ParticipantContactable
• Resource References: Account , ActivityDefinition , AdverseEvent , Appointment , AppointmentResponse , ... Show 42 more , AuditEvent , CarePlan , Claim , ClaimResponse , Communication , Contract , CoverageEligibilityRequest , DetectedIssue , Device , DeviceAlert , DeviceAssociation , DeviceRequest , DiagnosticReport , EligibilityRequest , Encounter , ExplanationOfBenefit , Flag , Group , GuidanceResponse , HealthcareService , ImagingStudy , Immunization , List InsurancePlan , InsuranceProduct , itself , MeasureReport , MedicationDispense , MedicationRequest , NutritionIntake , Observation , OrganizationAffiliation , PaymentReconciliation , PlanDefinition , PractitionerRole , Procedure , ProcedureRequest , Provenance , RegulatedAuthorization , RequestOrchestration , ResearchStudy , Schedule , SupplyDelivery ServiceRequest , Specimen , Task and SupplyRequest UsageContext
• Extension References: CommunicationRequest Initiating Location , Consent Location of Access restriction , DiagnosticReport Location Performed , Event Location and Receiving person

8.7.3 8.7.4 Resource Content

 

Alternate Additional definitions: Master Definition ( XML , + JSON ), , XML Schema / Schematron (for ) + JSON Schema , ShEx (for Turtle ) + see the extensions , the spreadsheet version & the dependency analysis

8.7.3.1 8.7.4.1 Terminology Bindings

Location.operationalStatus Location.type Location.physicalType

Path	Definition ValueSet	Type	Reference Documentation
Location.status	LocationStatus	Required	Indicates whether the location is still in use.
Location.operationalStatus	Hl7VSBedStatus Required (a valid code from bedStatus )	Preferred	LocationStatus Value Set of codes that specify the state of a bed in an inpatient setting, and is used to determine if a patient may be assigned to it or not.
Location.code	The operational status if the location (where typically a bed/room) Iso316612	Preferred Example	v2 Bed Status This value set defines the ISO 3166 Part 1 2-letter codes
Location.mode	LocationMode	Required	Indicates whether a resource instance represents a specific location or a class of locations.
Location.type	ServiceType	Required Preferred	LocationMode This value set defines an example set of codes of service-types.
Location.form	Indicates the LocationForm (a valid code from Location type of function performed at the location. )	Extensible Example	ServiceDeliveryLocationRoleType This example value set defines a set of codes that can be used to indicate the physical form of the Location.
Location.characteristic	Physical form of the location LocationCharacteristic	Example	LocationType Example Set of Location Characteristics

8.7.4 8.7.5 Notes

• Multiple Organizations or Practitioners may provide services at a Location. These references are not kept in Location, but can be found in the models for Organization and Practitioner instead.
• Locations may range from whole buildings to cabinets; it is possible to relate smaller Locations to their containing bigger Location using the Location.partOf element.
• Location.position is expressed using the same syntax, datum and reference system as used in Google Earth's KML files, see Google/OGS's KML .
• Location availability exceptions such as public holidays or planned maintenance can be blocked out using the hoursOfOperation.notAvailableTime properties. It might be defined as just a textual description (e.g. Public Holidays) in which case the user would need to know what that means. Preferably it should include the actual start/end dates that is it not available.
  Not intended to store ongoing historic data here, but the most recent/upcoming relevant data (however nothing prevents that data from existing either)

8.7.4.1 8.7.5.1 Location Mode

The Location.mode element can be used to indicate whether a Location resource represents a specific (potentially identifiable) Location ('instance'), or a class of Locations ('kind'). Especially Resources capturing orders, resource scheduling, plans and definitions may refer to Locations in 'kind' mode. For these domains, it is often not necessary to refer to a specific Location, but rather to a class of Locations. An example of this is found in planning, where we need to allocate an "isolation room" "isolation room" for a patient, or need to dispatch "an ambulance" "an ambulance" at a certain time. In these cases it is not important to identify exactly which isolation room or ambulance is allocated, and it is sufficient to just indicate a 'kind' of Location.

Note that 'kind' should not be used to represent Locations where an actual instance of a Location was involved, but by identifying information is missing. missing information. E.g. when a patient arrived 'by ambulance', but it is not known by which ambulance, this should be represented using a Location in 'instance' mode with a missing identifier, not a Location of 'kind' ambulance.

Some of Location's data elements are only relevant when mode is 'instance' and should not be used when mode is 'kind':
(however this information could still be included if was relevant, such as when it is a generic item, but not globally generic, e.g. a Burgers MU Medical Centre ambulance)

• Location.identifier
• Location.telecom
• Location.address
• Location.position
• Location.status
• Location.managingOrganization

8.7.5 8.7.6 Example Location Hierarchy

An example location hierarchy should help give some guidance as to one example of how a location hierarchy could look within a fictitious Hospital.
(The nesting here would be the "part-of" "part-of" structure of the location)

Hospital A Building C (instance) East Wing (instance) Level 1 (instance) Reception (instance) Nurses Station EM-ns1 (instance) Medication Cupboard A (instance) Room 1 (instance) Room 1a (instance) - space in room separatable via a curtain Bed 1a (instance) - always in this room Room 1b (instance) Trolley 43 (instance) - moves about Room 1d (instance) Trolley 19 (instance) - moves about Room 2 (instance) ... Theatre EM-TA (instance) Coridor (generic) Level 2 (instance) Reception (instance) ... Nurses Station EM-ns1 (instance) Medication Cupboard A (instance) Coridor (generic) Mobile Services (kind) Ambulance (kind) Ambulance AMB1 (instance) Ambulance AMB2 (instance)

Hospital A Building C (instance)
    East Wing (instance)
        Level 1 (instance)
            Reception (instance)
            Nurses Station EM-ns1 (instance)
                Medication Cupboard A (instance)
            Room 1 (instance)
                Room 1a (instance) - space in room separatable via a curtain
                    Bed 1a (instance) - always in this room
                Room 1b (instance)
                    Trolley 43 (instance) - moves about
                Room 1d (instance)
                    Trolley 19 (instance) - moves about
                Room 2 (instance)
                    ...
            Theatre EM-TA (instance)
            Corridor (generic)
        Level 2 (instance)
            Reception (instance)
                ...
            Nurses Station EM-ns1 (instance)
                Medication Cupboard A (instance)
            Corridor (generic)
Mobile Services (kind)
    Ambulance (kind)
        Ambulance AMB1 (instance)
        Ambulance AMB2 (instance)

Note: Wards/departments are not part of this structure - these would form part of the Organizational Hierarchy.

8.7.5.1 8.7.6.1 Positional Searching

8.7.6.1.1 Near: Locations within a specified distance of a provided geocode

Searching for locations often require that a facility is within a specified distance of a particular specified point. For example, to locate healthcare facilities within 2kms 11.2 kms of a clients client's home, or the current geo-coded position of a practitioner travelling between patients (read from a mobile phone or device).

GET [base]/Location?near=-83.694810:42.256500&near-distance=11.20||km...

 GET [base]/Location?near=-83.694810|42.256500|11.20|km...

Note: The near search parameters distance and distance unit parameter components are optional, if the units are missing, kms are not able to be used with multiples thus assumed. If the distance parameter component is missing, then the server may choose its own interpretation of what near enough is to be included in the search results.

Note: The STU3 version of this functionality did not support the multiple seperator separator , should not be used with near or near-distance. chaining. The update to this format now supports both of these use cases.
(And the near-distance was deprecated as a result of this change too)

The distance between the location and the provided point is often used as one of the determining factors for selection of the location. So this value is included in the results.
However the value cannot be inside the Location resource as it is different depending on the point of reference in the search. So the distance between is included in the search section of the bundle entry. Where multiple near positions are included, the distance to the closest point provided may be included.

<entry> <resource> <Location> <!-- location details --> </Location> </resource> <search> <extension url="http://hl7.org/fhir/StructureDefinition/location-distance"> <valueDistance > <!-- The distance that this location resource is from the provided point in the query --< </value value="10.5"/> </unit value="km"/> </valueDistance> </extension> </search> </entry>

<entry> 
    <resource>
        <Location>
            <!-- location details -->
        </Location>
    </resource>
    <search>
        <extension url="http://hl7.org/fhir/StructureDefinition/location-distance">
            <valueDistance >
                <!-- The distance that this location resource is from the provided point in the query -->
                <value value="10.5"/>
                <unit value="km"/>
            </valueDistance>
        </extension>
    </search>
</entry> 

Note: When sorting by the near search parameter the results can be considered an ordered set, even if the implementation does not provide calculated distances to the point provided. Given the variety of possible implementations, this ordering might not be dependable. If no bounding distance is provided via the search parameter, this can be considered as an ordered set of closest matches (up to an implied or explicit count).

If the expectation is that the response is ordered by near, then near MUST be provided as a search parameter in the request as well. A Bad Request will be returned if sorting by near is requested without the near search parameter.
For example:

 GET [base]/Location?near=-83.694810|42.256500|11.20|km&_sort=near

8.7.6.1.2 Contains: Locations with a boundary that contains the provided geocode

Locations can also include a definition of their boundary shape in the standard extension location-boundary-geojson . This is very useful with defining explicit coverage areas.
The special contains search parameter tests that the geocoded point(s) provided (expressed as [latitude]|[longitude] using the WGS84 datum) are contained by the defined boundary.

    GET [base]/Location?contains=-83.694810|42.256500

Support for multiple points can also be provided using the , syntax which is interpreted as the location returned in the search contains at least 1 of the provided co-ordinates.

Note: Searching this data requires specialized geo-spatial search infrastructure, or other approximating implementations.

8.7.6 8.7.7 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
address	string	A (part of the) address server defined search that may match any of the location string fields in the Address, including line, city, district, state, country, postalCode, and/or text	Location.address
address-city	string	A city specified in an address	Location.address.city
address-country	string	A country specified in an address	Location.address.country
address-postalcode	string	A postal code specified in an address	Location.address.postalCode
address-state	string	A state specified in an address	Location.address.state
address-use	token	A use code specified in an address	Location.address.use
characteristic	token	Physical form of the location (e.g. bed/ward/site/virtual)	Location.form
code	token	The code of the location	Location.code
contains	special	Select locations that contain the specified co-ordinates	Location.extension('http://hl7.org/fhir/StructureDefinition/location-boundary-geojson').value
endpoint	reference	Technical endpoints providing access to services operated for the location	Location.endpoint ( Endpoint )
identifier	token	An identifier for the location	Location.identifier
mode	token	The mode of the location (instance | kind)	Location.mode
name	string	A portion of the location's name or alias	Location.name | Location.alias
near	token special	The Search for locations where the location.position is near to, or within a specified distance of, the provided coordinates expressed as [latitude]:[longitude] [latitude]|[longitude]|[distance]|[units] (using the WGS84 datum, see notes) to find locations notes). Servers which support the near to (servers may search using a square rather than a circle parameter SHALL support the unit string 'km' for efficiency) Requires kilometers and SHOULD support '[mi_us]' for miles, support for other units is optional. If the near-distance parameter to units are omitted, then kms should be provided also Location.position near-distance quantity A assumed. If the distance quantity is omitted, then the server can use its own discretion as to limit what distances should be considered near (and units are irrelevant). If the server is unable to understand the units (and does support the near search to locations within parameter), it MIGHT return an OperationOutcome and fail the search with a specific distance Requires http status 400 BadRequest. If the server does not support the near parameter, the parameter MIGHT report the unused parameter in a bundled OperationOutcome and still perform the search ignoring the near parameter. Note: The algorithm to also be included determine the distance is not defined by the specification, and systems might have different engines that calculate things differently. They could consider geographic point to point, or path via road, or including current traffic conditions, or just simple neighboring postcodes/localities if that's all it had access to.	Location.position
operational-status	token	Searches for locations (typically bed/room) that have an operational status (e.g. contaminated, housekeeping)	Location.operationalStatus
organization	reference	Searches for locations that are managed by the provided organization	Location.managingOrganization ( Organization )
partof	reference	A location of which this location is a part	Location.partOf ( Location )
status	token	Searches for locations with a specific kind of status	Location.status
type	token	A code for the type of location	Location.type