> ## Documentation Index > Fetch the complete documentation index at: https://docs.omophub.com/llms.txt > Use this file to discover all available pages before exploring further. # Vocabulary Releases > Learn about available OMOP vocabulary release versions, how to pin a specific release in API calls, and manage vocabulary updates from OHDSI Athena. The OMOPHub API supports multiple vocabulary release versions through a sophisticated schema-based versioning system. Each release contains the complete OHDSI vocabulary data for that time period, ensuring data consistency and enabling time-based analysis. ## Current Available Releases The following vocabulary releases are currently available in the system: | Version | Release Date | FHIR CodeSystem ID | Status | Default | Release Notes | | ---------- | ------------ | ------------------ | ------ | ------- | ----------------------------------------------------------------------------------------- | | **2026.1** | 2026-02-27 | `omop-v20260227` | Active | Yes | [Link](https://github.com/OHDSI/Vocabulary-v5.0/releases/tag/v20260227_1772176757.000000) | | **2025.2** | 2025-08-27 | `omop-v20250827` | Active | No | [Link](https://github.com/OHDSI/Vocabulary-v5.0/releases/tag/v20250827_1756288395.000000) | | **2025.1** | 2025-02-27 | `omop-v20250227` | Active | No | [Link](https://github.com/OHDSI/Vocabulary-v5.0/releases/tag/v20250227_1740652703.000000) | | **2024.2** | 2024-08-30 | `omop-v20240830` | Active | No | [Link](https://github.com/OHDSI/Vocabulary-v5.0/releases/tag/v20240830_1725004358.000000) | The **FHIR CodeSystem ID** column is what you pass to the FHIR Terminology Service for release-pinned instance reads and operations - e.g. `GET /fhir/r4/CodeSystem/omop-v20250827` or `CodeSystem/omop-v20250827/$lookup?...`. FHIR handlers accept both formats interchangeably: the OMOPHub version (`2025.2`) and the FHIR ID (`omop-v20250827`). The FHIR ID is computed deterministically from the release date (`omop-v` + `YYYYMMDD`). ## FHIR Code System URIs Each vocabulary release is served through both the REST API (by OMOP `vocabulary_id`) and the FHIR Terminology Service at `https://fhir.omophub.com/fhir/{r4,r4b,r5,r6}/` (by canonical FHIR system URI). The mapping below is stable across releases - only the underlying concepts change between versions. | FHIR System URI | OMOP `vocabulary_id` | | --------------------------------------------- | -------------------- | | `http://snomed.info/sct` | `SNOMED` | | `http://loinc.org` | `LOINC` | | `http://www.nlm.nih.gov/research/umls/rxnorm` | `RxNorm` | | `http://hl7.org/fhir/sid/icd-10` | `ICD10` | | `http://hl7.org/fhir/sid/icd-10-cm` | `ICD10CM` | | `http://hl7.org/fhir/sid/icd-10-pcs` | `ICD10PCS` | | `http://hl7.org/fhir/sid/icd-10-cn` | `ICD10CN` | | `http://hl7.org/fhir/sid/icd-10-gm` | `ICD10GM` | | `http://hl7.org/fhir/sid/icd-9-cm` | `ICD9CM` | | `http://hl7.org/fhir/sid/icd-9` | `ICD9Proc` | | `http://hl7.org/fhir/sid/icd-9-cn` | `ICD9ProcCN` | | `http://hl7.org/fhir/sid/icd-o-3` | `ICDO3` | | `http://hl7.org/fhir/sid/cvx` | `CVX` | | `http://hl7.org/fhir/sid/ndc` | `NDC` | | `http://www.nlm.nih.gov/research/umls/hcpcs` | `HCPCS` | | `http://www.whocc.no/atc` | `ATC` | | `http://unitsofmeasure.org` | `UCUM` | | `urn:iso:std:iso:11073:10101` | `MDC` | | `http://fdasis.nlm.nih.gov` | `UNII` | | `http://va.gov/terminology/medrt` | `MED-RT` | | `https://fhir-terminology.ohdsi.org` | OMOP unified omnibus | Source of truth is `apps/api/src/config/fhir-vocabularies.ts`. To get the live list from the running service, call `GET /fhir/r4/metadata?mode=terminology` - the `TerminologyCapabilities` resource enumerates every supported `codeSystem.uri`. ## Version Abbreviations For convenience, the API supports several abbreviations for version specification: | Abbreviation | Maps To | Description | | ------------ | -------- | ---------------------------------------- | | `latest` | `2026.1` | Always points to the most recent release | | `default` | `2026.1` | Same as latest - the system default | | `current` | `2026.1` | Alias for the default version | | `2026v1` | `2026.1` | Half-based abbreviation | | `2025v2` | `2025.2` | Half-based abbreviation | | `2025v1` | `2025.1` | Half-based abbreviation | | `2024v2` | `2024.2` | Half-based abbreviation | ## How to Select Vocabulary Versions You can specify which vocabulary version to use in your API requests using any of these methods: ### Method 1: Query Parameter (Recommended) Add the `vocab_release` parameter to any API endpoint: ```bash cURL theme={null} # Using specific version curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.1" \ -H "Authorization: Bearer YOUR_API_KEY" # Using abbreviation curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024v1" \ -H "Authorization: Bearer YOUR_API_KEY" # Using latest (default behavior) curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=latest" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```ts TypeScript theme={null} import { OMOPHub } from '@omophub/omophub-node'; const client = new OMOPHub(); // Using specific version const { data: specific } = await client.search.basic('diabetes', { vocabRelease: '2024.1' }); // Using abbreviation const { data: abbrev } = await client.search.basic('diabetes', { vocabRelease: '2024v1' }); // Using latest (default — omit vocabRelease) const { data: latest } = await client.search.basic('diabetes'); ``` ```python Python theme={null} import requests headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } # Using specific version response = requests.get( 'https://api.omophub.com/v1/concepts/search', headers=headers, params={ 'query': 'diabetes', 'vocab_release': '2024.2' } ) # Using abbreviation response_abbrev = requests.get( 'https://api.omophub.com/v1/concepts/search', headers=headers, params={ 'query': 'diabetes', 'vocab_release': '2024v2' } ) # Using latest (default) response_latest = requests.get( 'https://api.omophub.com/v1/concepts/search', headers=headers, params={ 'query': 'diabetes', 'vocab_release': 'latest' } ) ``` ```r R theme={null} library(httr) # Using specific version response <- GET( "https://api.omophub.com/v1/concepts/search", add_headers(Authorization = "Bearer YOUR_API_KEY"), query = list( query = "diabetes", vocab_release = "2024.2" ) ) # Using abbreviation response_abbrev <- GET( "https://api.omophub.com/v1/concepts/search", add_headers(Authorization = "Bearer YOUR_API_KEY"), query = list( query = "diabetes", vocab_release = "2024v2" ) ) # Using latest (default) response_latest <- GET( "https://api.omophub.com/v1/concepts/search", add_headers(Authorization = "Bearer YOUR_API_KEY"), query = list( query = "diabetes", vocab_release = "latest" ) ) ``` ### Method 2: HTTP Header Use the `X-Vocab-Release` header: ```bash cURL theme={null} curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Vocab-Release: 2024.2" ``` ```ts TypeScript theme={null} import { OMOPHub } from '@omophub/omophub-node'; const client = new OMOPHub(); // Either pass `vocabRelease` per-call (preferred) or set // `vocabVersion` on the client to inject the `X-Vocab-Version` header. const { data } = await client.search.basic('diabetes', { vocabRelease: '2024.2' }); ``` ```python Python theme={null} import requests headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', 'X-Vocab-Release': '2024.2' } response = requests.get( 'https://api.omophub.com/v1/concepts/search', headers=headers, params={'query': 'diabetes'} ) ``` ## Default Version Behavior When no version is specified: * **Default Version**: `2025.2` * **Fallback**: If the default version is unavailable, the system uses the latest available active version * **Caching**: Responses are cached with version-specific keys to ensure consistency ## Version Comparison Example Here's how to compare concept availability across versions: ```python Python theme={null} import requests def compare_concept_across_versions(concept_code, vocabulary_id): """Compare a concept across different vocabulary versions.""" headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } versions = ['2025.2', '2025.1', '2024.2'] results = {} for version in versions: response = requests.get( 'https://api.omophub.com/v1/concepts/search', headers=headers, params={ 'query': concept_code, 'vocabulary_ids': vocabulary_id, 'vocab_release': version, 'page_size': 1 } ) data = response.json() if data.get('data'): concept = data['data'][0] results[version] = { 'found': True, 'concept_name': concept['concept_name'], 'standard_concept': concept.get('standard_concept'), 'valid_start_date': concept.get('valid_start_date'), 'valid_end_date': concept.get('valid_end_date') } else: results[version] = {'found': False} return results # Example usage concept_comparison = compare_concept_across_versions('E11.9', 'ICD10CM') for version, info in concept_comparison.items(): if info['found']: print(f"Version {version}: {info['concept_name']}") else: print(f"Version {version}: Not found") ``` ```ts TypeScript theme={null} import { OMOPHub } from '@omophub/omophub-node'; const client = new OMOPHub(); interface VersionInfo { found: boolean; conceptName?: string; standardConcept?: string | null; validStartDate?: string; validEndDate?: string; error?: string; } async function compareConcept(conceptCode: string, vocabularyId: string) { const versions = ['2026.1', '2025.2', '2025.1', '2024.2']; const results: Record = {}; for (const version of versions) { const { data, error } = await client.search.basic(conceptCode, { vocabularyIds: [vocabularyId], vocabRelease: version, pageSize: 1, }); if (error) { results[version] = { found: false, error: error.message }; } else if (data && data.length > 0) { const concept = data[0]; results[version] = { found: true, conceptName: concept.concept_name, standardConcept: concept.standard_concept, validStartDate: concept.valid_start_date, validEndDate: concept.valid_end_date, }; } else { results[version] = { found: false }; } } return results; } // Example usage const results = await compareConcept('E11.9', 'ICD10CM'); for (const [version, info] of Object.entries(results)) { console.log(`Version ${version}: ${info.found ? info.conceptName : 'Not found'}`); } ``` ## Version-Specific Features ### Temporal Queries Query concepts as they existed at specific points in time: ```bash theme={null} # Get diabetes concepts as they existed in 2024v2 curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.2" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Historical Analysis Compare vocabulary evolution over time: ```bash theme={null} # Compare concept relationships across versions curl -X GET "https://api.omophub.com/v1/concepts/123456/relationships?vocab_release=2024.2" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Migration Support Validate concept mappings when upgrading between versions: ```bash theme={null} # Validate proposed mappings against OMOP standards curl -X POST "https://api.omophub.com/v1/mappings/validate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"mappings":[{"source_concept_id":201826,"target_concept_id":1569178005,"mapping_type":"Maps to"}]}' ``` ## Version Support Policy ### Active Versions * **Current + 2 previous releases** are actively supported ### Deprecated Versions * **Removal notice** provided 90 days before discontinuation ## Troubleshooting ### Common Issues #### Version Not Found ```json theme={null} { "error": "VOCABULARY_VERSION_NOT_FOUND", "message": "Vocabulary version '2023.1' is not available", "available_versions": ["2026.1", "2025.2", "2025.1", "2024.2"] } ``` **Solution**: Use the `/v1/vocabularies/releases` endpoint to check available versions. #### Version Mismatch in Results If you receive unexpected results, verify the version is being applied correctly: ```bash theme={null} # Check which version was actually used curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.2" \ -H "Authorization: Bearer YOUR_API_KEY" \ -v # Verbose mode shows response headers ``` Look for the `X-Vocab-Release-Used` header in the response to confirm the version. ## FAQ The system automatically uses the default version (`2026.1`). This provides the most recent vocabulary data and optimal performance through caching. No, each API request operates against a single vocabulary version. To compare across versions, make separate requests for each version. Major vocabulary updates typically occur twice a year (February and August), following the [OHDSI vocabulary release cycles](https://github.com/OHDSI/Vocabulary-v5.0/wiki/Release-planning).