The FHIR R4 Location resource describes the physical or virtual place where healthcare services are provided. This includes clinics, hospitals, departments, and telehealth service locations. It is commonly referenced by other resources like Encounter, PractitionerRole, and Organization.
Health Gorilla exposes Location as part of its FHIR R4 API to support identification and reference of service delivery sites across clinical workflows.
Use Cases
- Identifying the facility where a patient was seen or treated
- Associating a provider with a specific service location
- Filtering encounters or appointments by location
Scope and Behavior
This documentation describes the FHIR R4 API interface for Location. Health Gorilla’s platform may use additional internal services and data standards to acquire, normalize, and route administrative and facility information. Only the FHIR R4–exposed behavior is documented here.
Health Gorilla supports a subset of the HL7 FHIR R4 Location resource. Not all optional elements defined in the HL7 specification may be stored, indexed, or returned. Unsupported or unrecognized elements may be ignored or normalized during processing.
In Health Gorilla, Location is most commonly accessed as part of patient record retrieval and administrative workflows, where facility and service site information is referenced by encounters, appointments, and practitioner roles.
Authentication
All requests to the FHIR R4 API require OAuth 2.0 authentication using a bearer token. Unauthorized requests return 401 Unauthorized responses.
Required Scope
location.read for GET
For more information, go to: OAuth 2.0 Authentication.
Search Behavior
Searches are scoped to the authenticated tenant. Results are returned as a FHIR Bundle. Pagination may be applied. Use standard FHIR pagination links (Bundle.link) to retrieve additional result pages.
Note: Supported parameters and behavior may vary by configuration.
Search Parameters
Location supports a directory search and a proximity search. In the proximity search, near is required and takes a city or a postal code.
| Parameter | Required | Description |
|---|---|---|
near | Required in the proximity search | The city or postal code to search around. |
organization | No | Returns the locations belonging to the given organization, as Organization/{id}. |
type | No | The kind of location to return. |
name | No | Filters on the location name. |
address-state | No | Filters on the state in the location address. |
address-city | No | Filters on the city in the location address. |
address-postalcode | No | Filters on the postal code in the location address. |
test-code | No | Returns the locations that perform the given test. |
_count | No | Limits the number of results returned per page. |
Filter on the discrete address-state, address-city, and address-postalcode parameters. A combined address parameter isn't supported.
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type |
|---|---|---|---|
id | Unique FHIR ID for the location | 6b2a8a16-2131-49fb-b5f7-ef8cfe2a9a6c | id |
name | Name of the location | "Health Gorilla Main Clinic" | string |
status | Whether the location record is active | active, suspended, inactive | code |
mode | Indicates instance vs kind | instance, kind | code |
type | Type of facility or location | outpatient clinic, lab, pharmacy | CodeableConcept[] |
address | Physical or mailing address | City, state, postal code | Address |
telecom | Contact information | Phone, fax | ContactPoint[] |
managingOrganization | Organization responsible for the location | Organization/{id} | Reference(Organization) |
partOf | Larger location that this is part of | Location/{id} | Reference(Location) |
position | Geographic coordinates | latitude: 37.37, longitude: -122.03 | BackboneElement |
Notifications
The FHIR R4 API does not provide direct resource-change subscriptions for Location. Location resources may appear in payloads for related resources such as Encounter, PractitionerRole, or Appointment.
Error Handling
All Location operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses.
For more information, go to: Error Handling.