https://github.com/fderuiter/imednet-python-sdk
A Unofficial Python SDK that makes it easy to work with the iMednet REST API from your code or the command line. Manage studies, subjects, records, and more with a "friendly" interface. No need to worry about the low-level details.
https://github.com/fderuiter/imednet-python-sdk
api automation clinical clinical-trials data-integration edc healthcare imednet python research sdk
Last synced: about 1 month ago
JSON representation
A Unofficial Python SDK that makes it easy to work with the iMednet REST API from your code or the command line. Manage studies, subjects, records, and more with a "friendly" interface. No need to worry about the low-level details.
- Host: GitHub
- URL: https://github.com/fderuiter/imednet-python-sdk
- Owner: fderuiter
- License: mit
- Created: 2025-04-18T16:16:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-04T19:11:32.000Z (about 1 month ago)
- Last Synced: 2026-05-04T19:14:05.614Z (about 1 month ago)
- Topics: api, automation, clinical, clinical-trials, data-integration, edc, healthcare, imednet, python, research, sdk
- Language: Python
- Homepage: https://fderuiter.github.io/imednet-python-sdk/
- Size: 1.98 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# imednet
**Unofficial Python SDK for the iMednet clinical trials API.**
Full documentation:
[](https://pypi.org/project/imednet/)
[](https://pypi.org/project/imednet/)
[](https://pypi.org/project/imednet/)
[](https://pypi.org/project/imednet/)
[](LICENSE)
[](https://github.com/fderuiter/imednet-python-sdk/actions/workflows/ci.yml)
[](https://github.com/fderuiter/imednet-python-sdk)
This package simplifies integration with the iMednet REST API for clinical trial
management. It provides typed endpoint wrappers, helper workflows and a CLI so
researchers and developers can automate data extraction and submission without
reimplementing HTTP logic.
## Features
- Simple, consistent interface for API calls
- Automatic pagination across endpoints
- Pydantic models for requests and responses
- Workflow helpers for data extraction and mapping
- Pandas and CSV utilities
- Optional in-memory caching of study metadata
- Structured JSON logging and OpenTelemetry tracing
- Async client and command line interface
- **Form Designer**: Pythonic API for building and validating CRFs
---
## Architecture
The SDK is organized around a core HTTP client layer, endpoint wrappers that model
the iMednet API, workflow helpers that combine multiple endpoint calls, and a CLI
built on top of those pieces.
```mermaid
graph TD
CLI[CLI] --> |invokes| Workflows
Workflows --> |coordinate| Endpoints
Endpoints --> |use| Client["(HTTP Client)"]
Client --> |httpx| API
```
---
## Installation
```bash
# PyPI release
pip install imednet
```
### Optional Dependencies
To use export features, workflow plugins, or Airflow provider integrations, install the relevant extras/packages:
```bash
# Install all export dependencies
pip install "imednet[pandas,sqlalchemy,pyarrow,excel]"
# Or pick specific ones
pip install "imednet[sqlalchemy]" # For SQL export
pip install "imednet[pyarrow]" # For Parquet export
pip install "imednet[excel]" # For Excel export
# Workflow plugin package
pip install imednet-workflows
# Airflow provider package
pip install apache-airflow-providers-imednet apache-airflow-providers-amazon
```
### Development Version
```bash
pip install git+https://github.com/fderuiter/imednet-python-sdk.git@main
```
---
## Quick Start
Set your credentials by copying the environment template or exporting them directly:
```bash
# Option 1: Use a .env file (recommended)
cp .env.example .env
# Option 2: Export directly to your shell
export IMEDNET_API_KEY="your_api_key"
export IMEDNET_SECURITY_KEY="your_security_key"
# Optional: Custom base URL for the API endpoint
# export IMEDNET_BASE_URL="https://example.com"
```
### Synchronous Example
```python
from dotenv import load_dotenv
from imednet import ImednetSDK, load_config
from imednet.utils import configure_json_logging
# Optional: Configure structured JSON logging
configure_json_logging()
# Load credentials from .env file or environment variables
load_dotenv()
cfg = load_config()
with ImednetSDK(
api_key=cfg.api_key,
security_key=cfg.security_key,
base_url=cfg.base_url,
) as sdk:
# List all studies available to the user
studies = sdk.studies.list()
for study in studies:
print(f"{study.study_name} ({study.study_key})")
```
### Asynchronous Example
```python
import asyncio
from dotenv import load_dotenv
from imednet import AsyncImednetSDK, load_config
from imednet.utils import configure_json_logging
async def main() -> None:
# Optional: Configure structured JSON logging
configure_json_logging()
# Load credentials from .env file or environment variables
load_dotenv()
cfg = load_config()
async with AsyncImednetSDK(
api_key=cfg.api_key,
security_key=cfg.security_key,
base_url=cfg.base_url,
) as sdk:
studies = await sdk.studies.async_list()
for study in studies:
print(f"{study.study_name} ({study.study_key})")
asyncio.run(main())
```
See [docs/async_quick_start.rst](docs/async_quick_start.rst) for more details.
---
## Configuration
The SDK and CLI read credentials from environment variables such as
`IMEDNET_API_KEY` and `IMEDNET_SECURITY_KEY`. You can set these in your shell or
use a `.env` file. Copy `.env.example` to `.env` to get started.
See [configuration](docs/configuration.rst) for the complete list of options.
Use `imednet.config.load_config()` to access these values in your code.
---
## CLI Usage
The package installs an `imednet` command with subcommands for studies, sites,
subjects, records, jobs, queries and more. Use `imednet --help` to explore all
options.
*(Note: If you are running the project from source or a local clone, make sure to first install dependencies with `poetry install`. Then, prefix commands with `poetry run`, e.g., `poetry run imednet --help`)*
### Data Export
Example of exporting a subset of variables:
```bash
imednet export sql MY_STUDY table sqlite:///data.db --vars AGE,SEX --forms 10,20
```
When the connection string uses SQLite, the command splits the output into one
table per form to avoid the 2000 column limit (in this case, the `table`
argument is ignored). Pass ``--single-table`` to disable this behaviour and use
the specified table name. See ``docs/cli.rst`` for full examples.
---
## Documentation & Resources
- **API Documentation**: Full documentation is available at
.
- **Official iMednet API Docs**: .
- **Postman Collection**: Download
[`imednet.postman_collection.json`](imednet.postman_collection.json) and import it
into Postman to explore and test the API endpoints.
---
## Development & Contributing
### Tech Stack
- Python 3.10–3.12
- httpx, pydantic, typer, tenacity, python-dotenv
### Prerequisites
- [Poetry](https://python-poetry.org/docs/) (for dependency management)
- [Make](https://www.gnu.org/software/make/) (optional, for building docs)
### Project Structure
```
.
├── docs/ - Sphinx documentation
├── examples/ - Usage samples
├── imednet/ - SDK package
├── scripts/ - Helper scripts
└── tests/ - Unit and integration tests
```
### Testing & Development
```bash
./scripts/setup.sh # once
poetry run ruff check --fix .
poetry run black --check .
poetry run isort --check --profile black .
poetry run mypy src/imednet
poetry run pytest -q
```
After running tests, validate documentation builds cleanly (no warnings):
```bash
make docs
```
See [AGENTS.md](AGENTS.md) for full documentation guidelines.
### Smoke-test workflow
The optional [smoke.yml](.github/workflows/smoke.yml) action runs the `tests/live` suite.
It relies on repository secrets `APIKEY` and `SECURITYKEY` and sets `IMEDNET_RUN_E2E`.
Use the workflow to confirm real API access on demand or via its nightly schedule.
INFO-level log messages stream to the terminal during these runs, making it easier to
debug failures.
### Building & Publishing
```bash
python -m build
python -m twine upload dist/*
```
Pushing a Git tag like `v0.1.4` triggers the GitHub Actions workflow that builds
and publishes the package to PyPI.
### Versioning & Changelog
This project follows [Semantic Versioning](https://semver.org). See
[GitHub Releases](https://github.com/fderuiter/imednet-python-sdk/releases) for release history.
### Contributing
Contributions are welcome! See the
[contributing guide](docs/contributing.rst) and
[CONTRIBUTING.md](CONTRIBUTING.md) for full details.
---
## Troubleshooting
**Missing or invalid required environment variable(s)**
If you see an error like `Error: IMEDNET_API_KEY and IMEDNET_SECURITY_KEY environment variables must be set.` (CLI) or `API key and security key are required` (SDK), or an "Unauthorized" or "Forbidden" (403) API error, ensure you have set valid keys in your shell or in a `.env` file in the directory where you run the script (avoid using "dummy" keys). See [Configuration](#configuration).
**ModuleNotFoundError when running the CLI locally**
If you are running the `imednet` CLI from source (e.g., `poetry run imednet`) and see a `ModuleNotFoundError` (such as `No module named 'imednet'`), ensure you have installed the project dependencies by running `poetry install` in the project root.
---
## License
This project is licensed under the MIT license. See [LICENSE](LICENSE) for
details.
---
## Acknowledgements
Built with open source libraries including httpx, pydantic and typer.