View raw Markdown
type: resourceresource: Location

Location

Introduction

Scope and Usage

A Location includes both incidental locations (a place which is used for healthcare without prior designation or authorization) and dedicated, formally appointed locations. Locations may be private, public, mobile or fixed and scale from small freezers to full hospital buildings or parking garages.

Examples of Locations are:

These locations are not intended to cover locations on a patient where something occurred (i.e. a patient's broken leg), but can happily cover the location where the patient broke the leg (the playground)

Boundaries and Relationships

Locations and Organizations are very closely related resources and can often be mixed/matched/confused.
The Location is intended to describe the more physical structures managed/operated by an organization, whereas the Organization is intended to represent the more conceptual hierarchies, such as a ward. Location may also be used to represent virtual locations, for example for telehealth visits.
As noted in the Event pattern, a Location represents where a service is performed. An Organization can represent who performed the service.

A Location is valid without an address in cases where it could be purely described by a geo-coded location in remote areas, or when recorded by a device. Locations with a mode = "kind" would also likely not have an address, as they are just a type of location, but could also have an address where they can be found at the address.

Another use of location could be for describing a Jurisdiction. This jurisdiction may be considered a classified boundary which could be a combination of a physical boundary, and some other discriminator(s):

Notes

Notes

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" for a patient, or need to dispatch "an ambulance" at a certain time. In these cases it is not important to identify exactly which isolation room or ambulance is allocated, 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 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 Medical Centre ambulance)

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" 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) 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.

Positional Searching

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 specified point. For example, to locate healthcare facilities within 11.2 kms of a 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|11.20|km...

The distance and distance unit parameter components are optional, if the units are missing, kms are to be 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 separator , or 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>

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

</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

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.

StructureDefinition

Elements (Simplified)

Mappings

Implementation Guide

implementationguide-Location-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="Location-core"/>
  <version value="0.01"/>
  <name value="LocationHL7Extensions"/>
  <title value="Location  H L7  Extensions"/>
  <status value="draft"/>
  <date value="1970-01-01T10:00:00+10:00"/>
  <publisher value="HL7"/>
  <description value="Defines common extensions used with or related to the Location resource"/>
</ImplementationGuide>

Resource Packs

list-Location-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="Location-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/Location-core"/>
    </item>
  </entry>
</List>

Search Parameters

Servers which support the near parameter SHALL support the unit string 'km' for kilometers and SHOULD support '[mi_us]' for miles, support for other units is optional. If the units are omitted, then kms should be assumed. If the distance is omitted, then the server can use its own discretion as to 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 parameter), it MIGHT return an OperationOutcome and fail the search with a 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 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

Full Search Parameters

Examples

Full Examples

Mapping Exceptions

location-fivews-mapping-exceptions.xml

Divergent Elements

Unmapped Elements

location-participant-mapping-exceptions.xml

Divergent Elements

location-participantcontactable-mapping-exceptions.xml

Divergent Elements

Unmapped Elements