# OHDSI WebAPI Client (Python)
[](https://pypi.org/project/ohdsi-webapi-client/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
Alpha-stage Python client for interacting with an OHDSI WebAPI instance.
## MVP Scope
- Info & health check
- Sources listing
- Vocabulary: concept lookup, search (basic), hierarchy (descendants)
- Concept Set: CRUD, expression export, resolve (included concepts)
- Cohort Definitions: CRUD, generate, job polling, inclusion stats, counts
## Install (development)
```bash
poetry install
```
(Ensure local venv is in-project: `.venv/` created via `poetry.toml`.)
## Environment Configuration
Copy the sample environment file and customize:
```bash
cp .env.sample .env
# Edit .env with your settings
```
The `.env` file is automatically loaded when you import the package. Key settings:
- `OHDSI_WEBAPI_BASE_URL`: Your WebAPI server URL
- `OHDSI_WEBAPI_AUTH_TOKEN`: Authentication token (optional)
- `OHDSI_CACHE_ENABLED`: Enable/disable caching (default: true)
- `OHDSI_CACHE_TTL`: Cache TTL in seconds (default: 300)
- `OHDSI_CACHE_MAX_SIZE`: Maximum cache entries (default: 128)
- `INTEGRATION_WEBAPI`: Enable live integration tests (default: 0)
### Interactive Development
The `.env` file works seamlessly with Poetry and IPython:
```bash
# Environment variables are automatically loaded
poetry run ipython
poetry run python your_script.py
poetry run pytest
```
## Install (from PyPI - when published)
```bash
pip install ohdsi-webapi-client
```
## Quickstart
```python
from ohdsi_webapi import WebApiClient
# Uses OHDSI_WEBAPI_BASE_URL from .env if set, otherwise explicit URL
client = WebApiClient("https://atlas-demo.ohdsi.org/WebAPI")
# Check WebAPI health and version
info = client.info()
print(f"WebAPI version: {info.version}")
# List available data sources
sources = client.sources()
for src in sources:
print(f"Source: {src.source_key} - {src.source_name}")
# Search for concepts
diabetes_concepts = client.vocabulary.search("type 2 diabetes", domain_id="Condition")
print(f"Found {len(diabetes_concepts)} diabetes concepts")
# Get a specific concept
metformin = client.vocabulary.concept(201826) # Metformin
print(f"Concept: {metformin.concept_name}")
# Work with concept sets
concept_sets = client.conceptset() # List all concept sets
print(f"Available concept sets: {len(concept_sets)}")
# Get vocabulary domains
domains = client.vocabulary.domains()
print(f"Available domains: {[d['domainId'] for d in domains[:5]]}")
client.close()
```
## API Design Philosophy
### Predictable REST-Style Methods
This client uses a **predictable naming convention** that mirrors WebAPI REST endpoints exactly, making it self-documenting for developers:
| REST Endpoint | Python Method | Description |
|--------------|---------------|-------------|
| `GET /info` | `client.info()` | WebAPI version and health |
| `GET /source/sources` | `client.sources()` | List data sources |
| `GET /vocabulary/domains` | `client.vocabulary.domains()` | List all domains |
| `GET /vocabulary/concept/{id}` | `client.vocabulary.concept(id)` | Get a concept |
| `GET /conceptset/` | `client.conceptset()` | List concept sets |
| `GET /conceptset/{id}` | `client.conceptset(id)` | Get concept set by ID |
| `GET /conceptset/{id}/expression` | `client.conceptset_expression(id)` | Get concept set expression |
**Why This Approach:**
- **Self-documenting**: `client.conceptset()` clearly maps to `GET /conceptset/`
- **Predictable**: If you know the REST endpoint, you know the Python method
- **Beginner-friendly**: Easy to learn for engineers new to OHDSI
- **No confusion**: One clear way to do each operation
See the [Supported Endpoints](docs/supported_endpoints.md) page for the complete mapping.
## Testing
### Unit tests (mocked, fast)
```bash
poetry run pytest
```
These use `respx` to mock HTTP endpoints.
### Live integration tests (public demo, read-only)
Disabled by default. To run:
```bash
export INTEGRATION_WEBAPI=1
export OHDSI_WEBAPI_BASE_URL=https://atlas-demo.ohdsi.org/WebAPI
poetry run pytest tests/live -q
```
Only GET/read-only endpoints are exercised (concept lookup & search). Write operations are intentionally excluded to avoid mutating the shared demo server.
### Local full integration (future)
Spin up a local WebAPI + database (Docker) to safely test create/update/delete for concept sets and cohorts. (Compose file TBD.)
## Concept & Concept Sets Summary
- `client.vocabulary.concept(id)` fetches a single concept by ID
- `client.vocabulary.search(query)` returns concepts matching text
- `client.vocabulary.concept_descendants(id)` navigates hierarchy
- `client.conceptset()` lists all concept sets
- `client.conceptset(id)` gets a specific concept set
- `client.conceptset_expression(id)` gets the concept set expression
- `client.conceptset_items(id)` resolves expression to concrete included concepts
## Additional Documentation
See the docs directory for deeper guides:
- [OHDSI Sources](docs/sources.md) - working with data sources and CDM databases
- [Vocabulary & Concepts](docs/vocabulary.md) - concept lookup, search, and hierarchies
- [Finding Codes](docs/finding_codes.md) - techniques for discovering OMOP concept codes
- [Concept Sets](docs/concept_sets.md) - creating and managing concept collections
- [Cohorts](docs/cohorts.md) - cohort definition management and generation
- [Cohort Building](docs/cohort_building.md) - advanced cohort construction patterns
- [Supported Endpoints](docs/supported_endpoints.md) - which WebAPI endpoints are supported
- [Caching](docs/caching.md) - performance optimization with intelligent caching
## Roadmap
- Auth strategies & configuration
- Asynchronous job polling patterns
## License
Apache 2.0
Raw data
{
"_id": null,
"home_page": "https://github.com/clsweeting/ohdsi-webapi",
"name": "ohdsi-webapi-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "OHDSI, WebAPI, OMOP, ETL, Cohort, Healthcare",
"author": "Your Name",
"author_email": "you@example.com",
"download_url": "https://files.pythonhosted.org/packages/cf/f3/da742f1cfc7e8e9c0905f9742f30ce7005d8c5b346ff0b827a39d2c74a1a/ohdsi_webapi_client-0.4.0.tar.gz",
"platform": null,
"description": "# OHDSI WebAPI Client (Python)\n\n[](https://pypi.org/project/ohdsi-webapi-client/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/Apache-2.0)\n\nAlpha-stage Python client for interacting with an OHDSI WebAPI instance.\n\n## MVP Scope\n- Info & health check\n- Sources listing\n- Vocabulary: concept lookup, search (basic), hierarchy (descendants)\n- Concept Set: CRUD, expression export, resolve (included concepts)\n- Cohort Definitions: CRUD, generate, job polling, inclusion stats, counts\n\n## Install (development)\n```bash\npoetry install\n```\n\n(Ensure local venv is in-project: `.venv/` created via `poetry.toml`.)\n\n## Environment Configuration\nCopy the sample environment file and customize:\n```bash\ncp .env.sample .env\n# Edit .env with your settings\n```\n\nThe `.env` file is automatically loaded when you import the package. Key settings:\n- `OHDSI_WEBAPI_BASE_URL`: Your WebAPI server URL\n- `OHDSI_WEBAPI_AUTH_TOKEN`: Authentication token (optional)\n- `OHDSI_CACHE_ENABLED`: Enable/disable caching (default: true) \n- `OHDSI_CACHE_TTL`: Cache TTL in seconds (default: 300)\n- `OHDSI_CACHE_MAX_SIZE`: Maximum cache entries (default: 128)\n- `INTEGRATION_WEBAPI`: Enable live integration tests (default: 0)\n\n### Interactive Development\nThe `.env` file works seamlessly with Poetry and IPython:\n```bash\n# Environment variables are automatically loaded\npoetry run ipython\npoetry run python your_script.py\npoetry run pytest\n```\n\n## Install (from PyPI - when published)\n```bash\npip install ohdsi-webapi-client\n```\n\n## Quickstart\n```python\nfrom ohdsi_webapi import WebApiClient\n\n# Uses OHDSI_WEBAPI_BASE_URL from .env if set, otherwise explicit URL\nclient = WebApiClient(\"https://atlas-demo.ohdsi.org/WebAPI\")\n\n# Check WebAPI health and version\ninfo = client.info()\nprint(f\"WebAPI version: {info.version}\")\n\n# List available data sources\nsources = client.sources()\nfor src in sources:\n print(f\"Source: {src.source_key} - {src.source_name}\")\n\n# Search for concepts\ndiabetes_concepts = client.vocabulary.search(\"type 2 diabetes\", domain_id=\"Condition\")\nprint(f\"Found {len(diabetes_concepts)} diabetes concepts\")\n\n# Get a specific concept\nmetformin = client.vocabulary.concept(201826) # Metformin\nprint(f\"Concept: {metformin.concept_name}\")\n\n# Work with concept sets\nconcept_sets = client.conceptset() # List all concept sets\nprint(f\"Available concept sets: {len(concept_sets)}\")\n\n# Get vocabulary domains\ndomains = client.vocabulary.domains()\nprint(f\"Available domains: {[d['domainId'] for d in domains[:5]]}\")\n\nclient.close()\n```\n\n## API Design Philosophy\n\n### Predictable REST-Style Methods\nThis client uses a **predictable naming convention** that mirrors WebAPI REST endpoints exactly, making it self-documenting for developers:\n\n| REST Endpoint | Python Method | Description |\n|--------------|---------------|-------------|\n| `GET /info` | `client.info()` | WebAPI version and health |\n| `GET /source/sources` | `client.sources()` | List data sources |\n| `GET /vocabulary/domains` | `client.vocabulary.domains()` | List all domains |\n| `GET /vocabulary/concept/{id}` | `client.vocabulary.concept(id)` | Get a concept |\n| `GET /conceptset/` | `client.conceptset()` | List concept sets |\n| `GET /conceptset/{id}` | `client.conceptset(id)` | Get concept set by ID |\n| `GET /conceptset/{id}/expression` | `client.conceptset_expression(id)` | Get concept set expression |\n\n**Why This Approach:**\n- **Self-documenting**: `client.conceptset()` clearly maps to `GET /conceptset/`\n- **Predictable**: If you know the REST endpoint, you know the Python method\n- **Beginner-friendly**: Easy to learn for engineers new to OHDSI\n- **No confusion**: One clear way to do each operation\n\nSee the [Supported Endpoints](docs/supported_endpoints.md) page for the complete mapping.\n\n\n## Testing\n### Unit tests (mocked, fast)\n```bash\npoetry run pytest\n```\nThese use `respx` to mock HTTP endpoints.\n\n### Live integration tests (public demo, read-only)\nDisabled by default. To run:\n```bash\nexport INTEGRATION_WEBAPI=1\nexport OHDSI_WEBAPI_BASE_URL=https://atlas-demo.ohdsi.org/WebAPI\npoetry run pytest tests/live -q\n```\nOnly GET/read-only endpoints are exercised (concept lookup & search). Write operations are intentionally excluded to avoid mutating the shared demo server.\n\n### Local full integration (future)\nSpin up a local WebAPI + database (Docker) to safely test create/update/delete for concept sets and cohorts. (Compose file TBD.)\n\n## Concept & Concept Sets Summary\n- `client.vocabulary.concept(id)` fetches a single concept by ID\n- `client.vocabulary.search(query)` returns concepts matching text\n- `client.vocabulary.concept_descendants(id)` navigates hierarchy\n- `client.conceptset()` lists all concept sets\n- `client.conceptset(id)` gets a specific concept set \n- `client.conceptset_expression(id)` gets the concept set expression\n- `client.conceptset_items(id)` resolves expression to concrete included concepts\n\n## Additional Documentation\nSee the docs directory for deeper guides:\n- [OHDSI Sources](docs/sources.md) - working with data sources and CDM databases \n- [Vocabulary & Concepts](docs/vocabulary.md) - concept lookup, search, and hierarchies\n- [Finding Codes](docs/finding_codes.md) - techniques for discovering OMOP concept codes\n- [Concept Sets](docs/concept_sets.md) - creating and managing concept collections\n- [Cohorts](docs/cohorts.md) - cohort definition management and generation\n- [Cohort Building](docs/cohort_building.md) - advanced cohort construction patterns\n- [Supported Endpoints](docs/supported_endpoints.md) - which WebAPI endpoints are supported\n- [Caching](docs/caching.md) - performance optimization with intelligent caching\n\n## Roadmap\n- Auth strategies & configuration\n- Asynchronous job polling patterns\n\n\n## License\nApache 2.0\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python client for OHDSI WebAPI (MVP: info, sources, vocabulary, concept sets, cohorts).",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/clsweeting/ohdsi-webapi",
"Repository": "https://github.com/clsweeting/ohdsi-webapi"
},
"split_keywords": [
"ohdsi",
" webapi",
" omop",
" etl",
" cohort",
" healthcare"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "230f55fa35e1c8738e8691ab87062873d987fdd275a28fa43bf7b3c4e1c8f9c8",
"md5": "5a39a2f521a4983aeed3bf3f2e5a1b80",
"sha256": "23571d767aa0ceccbce4769e047b5faee3860eaef800de63b69d9dc9c2856aba"
},
"downloads": -1,
"filename": "ohdsi_webapi_client-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5a39a2f521a4983aeed3bf3f2e5a1b80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 36372,
"upload_time": "2025-08-13T08:22:01",
"upload_time_iso_8601": "2025-08-13T08:22:01.929156Z",
"url": "https://files.pythonhosted.org/packages/23/0f/55fa35e1c8738e8691ab87062873d987fdd275a28fa43bf7b3c4e1c8f9c8/ohdsi_webapi_client-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cff3da742f1cfc7e8e9c0905f9742f30ce7005d8c5b346ff0b827a39d2c74a1a",
"md5": "4ca9dd90f4674caff4b8a6a2a0cda3e5",
"sha256": "17a1723d97dd06624282f1b3b55663c93daa68f4e12067178508c8d4ed4ca410"
},
"downloads": -1,
"filename": "ohdsi_webapi_client-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "4ca9dd90f4674caff4b8a6a2a0cda3e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 31696,
"upload_time": "2025-08-13T08:22:03",
"upload_time_iso_8601": "2025-08-13T08:22:03.382220Z",
"url": "https://files.pythonhosted.org/packages/cf/f3/da742f1cfc7e8e9c0905f9742f30ce7005d8c5b346ff0b827a39d2c74a1a/ohdsi_webapi_client-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 08:22:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "clsweeting",
"github_project": "ohdsi-webapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ohdsi-webapi-client"
}
JSON
