Address — Structured address
Address breaks down a postal or physical address into standardised components. Supports international variations via district/state/country.
Purpose
Address is used by Patient, Practitioner, Organization, Location. Breaking down an address is crucial for: FHIR search by city/zip, geolocation, postal routing (USPS, La Poste), regulatory compliance (insurance coverage zone).
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
use | code | 0..1 | home, work, temp, old, billing. |
type | code | 0..1 | postal, physical, both. |
text | string | 0..1 | Plain-text fallback. |
line | string[] | 0..* | Street lines (number + name + apt). |
city | string | 0..1 | City. |
district | string | 0..1 | County / district / arrondissement. |
state | string | 0..1 | State / region / province. |
postalCode | string | 0..1 | Postal code. |
country | string | 0..1 | Country (ISO 3166-1 alpha-2/alpha-3). |
period | Period | 0..1 | Validity period. |
JSON example
US residential address:
{
"use": "home",
"type": "both",
"text": "100 Main St, Anytown, CA 90210, USA",
"line": ["100 Main St", "Apt 4B"],
"city": "Anytown",
"district": "Orange County",
"state": "CA",
"postalCode": "90210",
"country": "USA",
"period": { "start": "2020-01-01" }
}Common pitfalls
- Everything in
text: not indexable. Always decompose into line, city, postalCode. - country in free text: use ISO 3166 (FR, FRA, US, USA) for interop.
- postalCode as number: some codes contain letters (UK, CA). Always
string.
Related resources
- Patient.address — Patient addresses.
- Location.address — Care location address.
- Organization.address — Organization address.