Location

Overview

The Location resource represents physical places where healthcare services are provided within the Provider System Access API. Locations can be buildings, rooms, vehicles, or virtual spaces where patients receive care or administrative services are performed.

Key Use Cases:

Retrieve healthcare facility information
Access location contact details and addresses
Query locations by name or geographic area
Support care coordination and referrals

Relationships to Other Resources:

Organization - Organizations that manage or operate locations
Patient - Patients receive care at locations
Practitioner - Healthcare providers work at locations
Encounter - Healthcare encounters occur at locations

Resource Schema

Key fields in the Location resource:

{
  "resourceType": "Location",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/facility-id",
      "value": "FAC-123"
    }
  ],
  "status": "active|suspended|inactive",
  "name": "string",
  "alias": ["string"],
  "description": "string",
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
          "code": "HOSP|AMB|COMM|PHARM",
          "display": "Hospital"
        }
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone|fax|email|url",
      "value": "string",
      "use": "work"
    }
  ],
  "address": {
    "use": "work",
    "line": ["string"],
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string"
  },
  "managingOrganization": {
    "reference": "Organization/org-123"
  }
}

Key Fields:

id - Unique identifier for the location
name - Human-readable name of the location
identifier - External identifiers for the location
address - Physical address of the location
managingOrganization - Organization responsible for the location
telecom - Contact information for the location

Operations

Read

Retrieve a specific location by ID.

Production
Preview

GET /Location/{id}

Example Request
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/loc-123 \
    -H "Accept: application/fhir+json"

GET /Location/{id}

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/loc-123 \
    -H "Accept: application/fhir+json"

Search

Search for locations using various criteria.

Production
Preview

GET /Location?parameter=value
POST /Location/_search

GET /Location?parameter=value
POST /Location/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
`address`	token	No	Any part of address	`address=Main Street`
`address-city`	token	No	City name	`address-city=Sacramento`
`address-postalcode`	token	No	ZIP/postal code	`address-postalcode=95814`
`address-state`	token	No	State abbreviation	`address-state=CA`
`identifier`	token	No	Location identifier	`identifier=FAC-123`
`name`	reference	No	Location name	`name=Medical Center`
`organization`	reference	No	Managing organization	`organization=Organization/org-123`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=ge2023-01-01`
`_revinclude`	special	No	Include Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"	`_revinclude=Provenance:target`

Common Search Patterns

Find locations by name:

GET /Location?name=Medical%20Center&_count=10

Search by city:

GET /Location?address-city=Sacramento

Find by organization:

GET /Location?organization=Organization/org-123

Search by postal code:

GET /Location?address-postalcode=95814&_count=20

Examples

Request Examples

Production
Preview

Search by name
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Medical%20Center&_count=10"

Search by city
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "address-city=Sacramento"

Search by organization
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "organization=Organization/org-123"

Search by name
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Medical%20Center&_count=10"

Search by city
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "address-city=Sacramento"

Search by organization
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "organization=Organization/org-123"

Response Examples

Successful Search Response

Location Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Location",
        "id": "loc-123",
        "identifier": [
          {
            "system": "http://example.org/facility-id",
            "value": "FAC-001"
          }
        ],
        "status": "active",
        "name": "Sacramento Medical Center",
        "type": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                "code": "HOSP",
                "display": "Hospital"
              }
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "(916) 555-0100",
            "use": "work"
          },
          {
            "system": "url",
            "value": "https://www.sacmedcenter.org",
            "use": "work"
          }
        ],
        "address": {
          "use": "work",
          "line": ["2315 Stockton Blvd"],
          "city": "Sacramento",
          "state": "CA",
          "postalCode": "95817",
          "country": "US"
        },
        "managingOrganization": {
          "reference": "Organization/org-123",
          "display": "Sacramento Health System"
        }
      }
    }
  ]
}

Individual Location Response

Single Location Resource
{
  "resourceType": "Location",
  "id": "loc-456",
  "identifier": [
    {
      "system": "http://example.org/facility-id",
      "value": "CLINIC-789"
    }
  ],
  "status": "active",
  "name": "Downtown Family Clinic",
  "description": "Primary care clinic serving downtown Sacramento",
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
          "code": "AMB",
          "display": "Ambulatory"
        }
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "(916) 555-0200",
      "use": "work"
    },
    {
      "system": "fax",
      "value": "(916) 555-0201",
      "use": "work"
    }
  ],
  "address": {
    "use": "work",
    "line": ["1234 J Street", "Suite 200"],
    "city": "Sacramento",
    "state": "CA",
    "postalCode": "95814",
    "country": "US"
  },
  "managingOrganization": {
    "reference": "Organization/org-456",
    "display": "Community Health Partners"
  }
}

Empty Result Set

No Locations Found
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Integration Patterns

Common Workflows

1. Location Lookup for Patient Care

# Step 1: Search for location by name
GET /Location?name=Medical Center&_count=10

# Step 2: Get specific location details
GET /Location/loc-123

# Step 3: Find managing organization
GET /Organization/org-123

2. Geographic Location Search

# Step 1: Search by city and state
GET /Location?address-city=Sacramento&address-state=CA

# Step 2: Narrow by postal code
GET /Location?address-postalcode=95814

# Step 3: Get location contact information
GET /Location/loc-456

Organization - Organizations that manage or operate locations
Patient - Patients receive care at locations
Practitioner - Healthcare providers work at locations
Encounter - Healthcare encounters occur at locations

Include Parameters

Use _include and _revinclude to fetch related resources:

# Get location with provenance information
GET /Location?name=Medical Center&_revinclude=Provenance:target

# Get locations with recent updates
GET /Location?_lastUpdated=ge2023-01-01&_count=5

Error Handling

The Location resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

Location-Specific Error Scenarios

404 Not Found: Location ID doesn't exist or location is inactive
400 Bad Request: Invalid search parameters or malformed queries
Empty Results: No locations match the search criteria

Troubleshooting Tips

Empty Results: Try broader search criteria or check if data exists for the region
Invalid Parameters: Verify parameter names match the FHIR specification
Performance Issues: Use _count parameter to limit result sets and improve response times

Overview​

Resource Schema​

Operations​

Read​

Search​

Search Parameters​

Common Search Patterns​

Examples​

Request Examples​

Response Examples​

Successful Search Response​

Individual Location Response​

Empty Result Set​

Integration Patterns​

Common Workflows​

Related Resources​

Include Parameters​

Error Handling​

Location-Specific Error Scenarios​

Troubleshooting Tips​

Supported Profiles​