Location

Overview

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

Key Use Cases:

• Find healthcare facilities by address or geographic area
• Locate specific departments within healthcare organizations
• Discover service locations for insurance networks
• Verify facility contact information and accessibility features

Relationships to Other Resources:

• Organization - Organizations that manage or operate locations
• HealthcareService - Services available at specific locations
• PractitionerRole - Practitioners who work at locations
• Endpoint - Technical endpoints for services 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",
  "mode": "instance|kind",
  "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"
  },
  "physicalType": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
        "code": "bu|wi|ro|ve|ho|ca|rd",
        "display": "Building"
      }
    ]
  },
  "managingOrganization": {
    "reference": "Organization/org-123"
  },
  "partOf": {
    "reference": "Location/parent-location"
  }
}

Key Fields:

• id - Unique identifier for the location
• name - Human-readable name of the location
• type - Type of location (hospital, clinic, pharmacy, etc.)
• 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

GET /Location/{id}

Example Request

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

Preview

GET /Location/{id}

Example Request

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

Search

Search for locations using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production

GET /Location?parameter=value

Preview

GET /Location?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Location/_search

Preview

POST /Location/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
address	string	No	Any part of address	address=Main Street
address-city	string	No	City name	address-city=Sacramento
address-postalcode	string	No	ZIP/postal code	address-postalcode=95814
address-state	string	No	State abbreviation	address-state=CA
name	string	No	Location name (partial match)	name=Medical Center
organization	reference	No	Managing organization	organization=Organization/org-123
partof	reference	No	Parent location	partof=Location/hospital-main
type	token	No	Location type	type=HOSP

Common Search Patterns

Find locations in a specific city:

GET /Location?address-city=Sacramento&_count=10

Search by organization:

GET /Location?organization=Organization/org-123

Find hospitals in a state:

GET /Location?type=HOSP&address-state=CA

Search by postal code:

GET /Location?address-postalcode=95814

Examples

Request Examples

Production

Find locations by city

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

Search by organization

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

Find hospitals in geographic area

curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=HOSP&address-state=CA&_count=20"

Preview

Find locations by city

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

Search by organization

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

Find hospitals in geographic area

curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Location/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=HOSP&address-state=CA&_count=20"

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"
        },
        "physicalType": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
              "code": "bu",
              "display": "Building"
            }
          ]
        },
        "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"
  },
  "physicalType": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
        "code": "bu",
        "display": "Building"
      }
    ]
  },
  "managingOrganization": {
    "reference": "Organization/org-456",
    "display": "Community Health Partners"
  }
}

Integration Patterns

Common Workflows

1. Find Service Locations for Provider Network

# Step 1: Find organization
GET /Organization?name=Health System&type=prov

# Step 2: Get all locations for organization
GET /Location?organization=Organization/org-123

# Step 3: Get services available at locations
GET /HealthcareService?location=Location/loc-123

2. Geographic Provider Search

# Step 1: Find locations in area
GET /Location?address-city=Sacramento&address-state=CA

# Step 2: Find practitioners at those locations
GET /PractitionerRole?location=Location/loc-123

# Step 3: Get practitioner details
GET /Practitioner/prac-456

Related Resources

• Organization - Organizations that manage locations
• HealthcareService - Services provided at locations
• PractitionerRole - Practitioners working at locations
• Endpoint - Technical endpoints for location services

Include Parameters

Use _include to fetch related resources:

# Get locations with their managing organizations
GET /Location?address-city=Sacramento&_include=Location:organization

# Get locations with available services
GET /Location?type=HOSP&_include=Location:service

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 geographic search parameters or malformed address queries
• Empty Results: No locations match the search criteria in the specified area

Troubleshooting Tips

• No Geographic Results: Verify address parameters use correct state abbreviations and postal code formats
• Organization References: Ensure organization IDs are valid when searching by managing organization
• Location Hierarchy: Use partof parameter to find sub-locations within larger facilities

Supported Profiles

• HL7 FHIR R4 Location
• US Core Location
• DaVinci PDex Plan-Net Location