# OHDSI WebAPI Client (Python)
[](https://pypi.org/project/ohdsi-webapi-client/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
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
## Installation
```bash
pip install ohdsi-webapi-client
```
## Install for development
We use [poetry](https://python-poetry.org/) for dependency and package management. Clone the repo then install dependencies:
```bash
poetry install
```
This should create a virtual environment in `.venv/` within the repo directory.
## Environment Configuration
Copy the sample environment file and customize:
```bash
cp .env.sample .env
```
Only one setting is required:
- `OHDSI_WEBAPI_BASE_URL`: Your WebAPI server URL
The rest are optional:
- `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 is automatically loaded when working with the Poetry environment.
Remember to start your commands with `poetry run` to activate the shell:
```bash
# Environment variables are automatically loaded
poetry run ipython
poetry run python your_script.py
poetry run python -m pytest tests
```
A lot of helper commands have been provided in the [Makefile](./Makefile)
## 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 |
**This approach has some advantages**
- 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
However, it breaks down sometimes (eg. how do you name GET, POST and DELETE posts?). See the [Supported Endpoints](docs/supported_endpoints.md) page for the available mapping, as well as 'service-oriented' alterantives.
## Testing
### Unit tests (mocked, fast)
We use `respx` to mock HTTP endpoints.
```bash
poetry run pytest
```
or simply:
```bash
make test
```
### Live integration tests
Some integration tests have been provided but are disabled by default since they hit the public ohdsi.org server.
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.
## 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
- [Cohort Definitions & Cohorts](docs/cohort-definitions-and-cohorts.md) - cohort definition, and generating cohorts
- [Cohort Building](docs/cohort-building.md) - advanced cohort construction patterns
- [Supported Endpoints](docs/supported_endpoints.md) - which WebAPI endpoints are supported
- [Live testing](docs/live-testing.md) - testing with actual WebAPI
- [Debugging](docs/debugging.md) - especially in Cohort creation
- [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/b9/59/fb6afa1da92b25348af2893dd17a25221ad5d73dfea45c71fe015f1d6206/ohdsi_webapi_client-0.4.2.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\nPython 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## Installation \n```bash\npip install ohdsi-webapi-client\n```\n\n## Install for development\n\nWe use [poetry](https://python-poetry.org/) for dependency and package management. Clone the repo then install dependencies: \n\n```bash\npoetry install\n```\n\nThis should create a virtual environment in `.venv/` within the repo directory. \n\n\n## Environment Configuration\nCopy the sample environment file and customize:\n\n```bash\ncp .env.sample .env\n```\n\nOnly one setting is required:\n- `OHDSI_WEBAPI_BASE_URL`: Your WebAPI server URL\n\nThe rest are optional: \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\n### Interactive Development\n\nThe `.env` file is automatically loaded when working with the Poetry environment. \n\nRemember to start your commands with `poetry run` to activate the shell: \n\n```bash\n# Environment variables are automatically loaded\npoetry run ipython\npoetry run python your_script.py\npoetry run python -m pytest tests \n```\n\nA lot of helper commands have been provided in the [Makefile](./Makefile)\n\n\n## Quickstart\n\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**This approach has some advantages**\n\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\nHowever, it breaks down sometimes (eg. how do you name GET, POST and DELETE posts?). See the [Supported Endpoints](docs/supported_endpoints.md) page for the available mapping, as well as 'service-oriented' alterantives. \n\n\n## Testing\n### Unit tests (mocked, fast)\n\nWe use `respx` to mock HTTP endpoints.\n\n```bash\npoetry run pytest\n```\n\nor simply: \n\n```bash \nmake test \n```\n\n### Live integration tests \n\nSome integration tests have been provided but are disabled by default since they hit the public ohdsi.org server. \n\nTo 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```\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\n## Additional Documentation\n\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- [Cohort Definitions & Cohorts](docs/cohort-definitions-and-cohorts.md) - cohort definition, and generating cohorts\n- [Cohort Building](docs/cohort-building.md) - advanced cohort construction patterns\n- [Supported Endpoints](docs/supported_endpoints.md) - which WebAPI endpoints are supported\n- [Live testing](docs/live-testing.md) - testing with actual WebAPI\n- [Debugging](docs/debugging.md) - especially in Cohort creation\n- [Caching](docs/caching.md) - performance optimization with intelligent caching\n\n## Roadmap\n\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.2",
"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": "23f7c8642ae7f75d95c7b30f7ba1cea1d119ed25711e9e98fa2936c881b9f8f6",
"md5": "4c569441f2d60b83486c1098e3d57d7c",
"sha256": "9fc943bd0c29ce36d6dc5c2bf01b612b979e34d48a07c38f065ab23662c0393a"
},
"downloads": -1,
"filename": "ohdsi_webapi_client-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c569441f2d60b83486c1098e3d57d7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 39145,
"upload_time": "2025-08-18T13:33:16",
"upload_time_iso_8601": "2025-08-18T13:33:16.424026Z",
"url": "https://files.pythonhosted.org/packages/23/f7/c8642ae7f75d95c7b30f7ba1cea1d119ed25711e9e98fa2936c881b9f8f6/ohdsi_webapi_client-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b959fb6afa1da92b25348af2893dd17a25221ad5d73dfea45c71fe015f1d6206",
"md5": "2f5da11099105e6a3f108cfe90315a7b",
"sha256": "a6e6d19fd8840701680acbd46f20f8f85f0980d3c1b6b27bf2e90f59ec1fadb8"
},
"downloads": -1,
"filename": "ohdsi_webapi_client-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "2f5da11099105e6a3f108cfe90315a7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 33488,
"upload_time": "2025-08-18T13:33:17",
"upload_time_iso_8601": "2025-08-18T13:33:17.730582Z",
"url": "https://files.pythonhosted.org/packages/b9/59/fb6afa1da92b25348af2893dd17a25221ad5d73dfea45c71fe015f1d6206/ohdsi_webapi_client-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 13:33:17",
"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
