Skip to main content
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:
VersionRelease DateStatusDefaultRelease Notes
2025.22025-08-27ActiveYesLink
2025.12025-02-27ActiveNoLink
2024.22024-08-30ActiveNoLink
2024.12024-02-29ActiveNoLink

​
Version Abbreviations

For convenience, the API supports several abbreviations for version specification:
AbbreviationMaps ToDescription
latest2025.2Always points to the most recent release
default2025.2Same as latest - the system default
current2025.2Alias for the default version
2025v22025.2Quarter-based abbreviation
2025v12025.1Quarter-based abbreviation
2024v22024.2Quarter-based abbreviation
2024v12024.1Quarter-based abbreviation

​
How to Select Vocabulary Versions

You can specify which vocabulary version to use in your API requests using any of these methods: Add the vocab_release parameter to any API endpoint: 
# 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"

​
Method 2: HTTP Header

Use the X-Vocab-Release header: 
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Vocab-Release: 2024.1"

​
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: 
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', '2024.1']
    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")

​
Version-Specific Features

​
Temporal Queries

Query concepts as they existed at specific points in time: 
# 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: 
# Compare concept relationships across versions
curl -X GET "https://api.omophub.com/v1/concepts/123456/relationships?vocab_release=2024.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Migration Support

Validate concept mappings when upgrading between versions: 
# Check if concepts are still valid in newer version
curl -X GET "https://api.omophub.com/v1/concepts/validate?codes=E11.9,I10&vocab_release=latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Version Support Policy

​
Active Versions

  • Current + 4 previous releases are actively supported

​
Deprecated Versions

  • Removal notice provided 90 days before discontinuation

​
Troubleshooting

​
Common Issues

​
Version Not Found

{
  "error": "VOCABULARY_VERSION_NOT_FOUND",
  "message": "Vocabulary version '2023.1' is not available",
  "available_versions": ["2025.2", "2025.1", "2024.2", "2024.1"]
}
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: 
# Check which version was actually used
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.1" \
  -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 (2025.2). 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 (Q1, Q3), following the OHDSI vocabulary release cycles.
⌘I