Overview
OMOPHub exposes its vocabulary data through a standards-compliant FHIR Terminology Service at /fhir/{r4,r5,r6}/. Any FHIR-compatible client (HAPI FHIR, Firely, etc.) can query OMOP concepts using standard FHIR operations.
This is NOT a full FHIR server - it serves terminology resources only (CodeSystem, ConceptMap, ValueSet). For clinical resources, continue using your FHIR server and point it at OMOPHub for terminology resolution.
Endpoints
| Operation | Path | Description |
|---|
| Metadata | GET /fhir/{version}/metadata | CapabilityStatement or TerminologyCapabilities |
| List CodeSystems | GET /fhir/{version}/CodeSystem | Available CodeSystem resources |
| Read CodeSystem | GET /fhir/{version}/CodeSystem/{id} | Single CodeSystem by ID |
| $lookup | GET|POST /fhir/{version}/CodeSystem/$lookup | Concept details by code |
| $validate-code | GET|POST /fhir/{version}/CodeSystem/$validate-code | Check if a code is valid |
| $translate | GET|POST /fhir/{version}/ConceptMap/$translate | Translate between vocabularies |
| $expand | GET|POST /fhir/{version}/ValueSet/$expand | Expand a ValueSet to list matching codes |
| ValueSet $validate-code | GET|POST /fhir/{version}/ValueSet/$validate-code | Check if a code is in a ValueSet |
| $subsumes | GET|POST /fhir/{version}/CodeSystem/$subsumes | Test subsumption between concepts |
| $find-matches | GET|POST /fhir/{version}/CodeSystem/$find-matches | Find concepts by property criteria |
| $closure | POST /fhir/{version}/ConceptMap/$closure | Compute subsumption closure for a concept set |
| Batch | POST /fhir/{version}/ | Execute multiple GET operations in one request |
OMOPHub Extensions
These operations are OMOPHub-specific and not part of the FHIR Terminology Service specification.
| Operation | Path | Description |
|---|
| $diff | GET|POST /fhir/{version}/CodeSystem/$diff | Compare concepts between vocabulary versions |
FHIR Versions
All four FHIR versions are supported from the same endpoint:
/fhir/r4/ - FHIR R4 (4.0.1) - US Cures Act, EHDS mandate/fhir/r4b/ - FHIR R4B (4.3.0)/fhir/r5/ - FHIR R5 (5.0.0)/fhir/r6/ - FHIR R6 (6.0.0)/fhir/ - Defaults to R4
Authentication
Same as the REST API: Authorization: Bearer oh_xxx header. FHIR operations share the same API key, rate limits, and metering.
Content Type
All responses use Content-Type: application/fhir+json. Errors are returned as FHIR OperationOutcome resources.
CodeSystem URL
OMOP concepts are identified by the OHDSI community canonical URL:
https://fhir-terminology.ohdsi.org
Supported Vocabularies
Query the TerminologyCapabilities endpoint (GET /fhir/r4/metadata?mode=terminology) for the live list. Currently supported code systems:
| FHIR System URI | OMOP vocabulary_id | Description |
|---|
https://fhir-terminology.ohdsi.org | (unified) | All OMOP concepts by concept_id |
http://snomed.info/sct | SNOMED CT | Clinical terms |
http://loinc.org | LOINC | Lab tests, measurements |
http://www.nlm.nih.gov/research/umls/rxnorm | RxNorm | Drugs (US) |
http://hl7.org/fhir/sid/icd-10 | ICD10 | ICD-10 (WHO) |
http://hl7.org/fhir/sid/icd-10-cm | ICD10CM | ICD-10-CM (US) |
http://hl7.org/fhir/sid/icd-10-cn | ICD10CN | ICD-10 Chinese Edition |
http://hl7.org/fhir/sid/icd-10-gm | ICD10GM | ICD-10 German Edition |
http://hl7.org/fhir/sid/icd-10-pcs | ICD10PCS | ICD-10 Procedure Coding |
http://hl7.org/fhir/sid/icd-9-cm | ICD9CM | ICD-9-CM (legacy) |
http://hl7.org/fhir/sid/icd-9 | ICD9Proc | ICD-9 Procedures |
http://hl7.org/fhir/sid/icd-9-cn | ICD9ProcCN | ICD-9 Chinese Edition |
http://hl7.org/fhir/sid/cvx | CVX | Vaccines |
http://hl7.org/fhir/sid/ndc | NDC | Drug products (US) |
http://unitsofmeasure.org | UCUM | Units of measure |
urn:iso:std:iso:11073:10101 | MDC | Medical Device Codes |
http://www.whocc.no/atc | ATC | Drug classification (WHO) |
http://www.nlm.nih.gov/research/umls/hcpcs | HCPCS | Procedures (US outpatient) |
http://hl7.org/fhir/sid/icd-o-3 | ICDO3 | Oncology morphology |
http://fdasis.nlm.nih.gov | UNII | Substance identifiers |
http://va.gov/terminology/medrt | MED-RT | Medication reference |
CPT4 (http://www.ama-assn.org/go/cpt) is excluded due to AMA licensing restrictions.
Queries for CPT4 codes return a 403 OperationOutcome.
Two Access Patterns
1. By concept_id:
GET /fhir/r4/CodeSystem/$lookup?system=https://fhir-terminology.ohdsi.org&code=201826
GET /fhir/r4/CodeSystem/$lookup?system=http://snomed.info/sct&code=44054006
Designations (Synonyms)
$lookup responses include designation entries for concept synonyms. Each
designation has a language code and a value string. These are the alternate
names from the OMOP concept_synonym table.
Property Naming
Standard OMOP properties use kebab-case names for interoperability. Relationship properties use their OMOP relationship names (e.g., Maps to, Is a).
Standard OMOP properties
| Property | Type | Description |
|---|
concept-id | integer | OMOP concept_id |
source-concept-code | Coding | Original source code as FHIR Coding (system URI + code) |
concept-name | string | OMOP concept_name |
domain-id | code | OMOP domain (Condition, Drug, Measurement, etc.) |
vocabulary-id | code | OMOP vocabulary_id (SNOMED, ICD10CM, LOINC, etc.) |
concept-class-id | code | OMOP concept_class_id (Clinical Finding, Disorder, etc.) |
standard-concept | code | S=Standard, C=Classification, NS=Non-standard |
inactive | boolean | Whether concept is inactive |
valid-start-date | date | Date concept became valid |
valid-end-date | date | Date concept becomes invalid |
invalid-reason | code | D=Deleted, U=Updated (omitted if valid) |
Relationship properties
| Property | Type | Description |
|---|
Maps to | Coding | Standard concept mapping |
Mapped from | Coding | Inverse of Maps to |
Is a | Coding | Parent/supertype |
Subsumes | Coding | Child/subtype |
property query parameter on $lookup to request specific properties
(e.g. property=concept-id&property=domain-id). When omitted, all standard
properties are returned.
Metering
Each FHIR operation counts as 1 API call against your plan quota (shared with REST API calls).
See Also
