An open source API
to perform clinically validated score calculations.
This project is licensed under the terms of the MIT license.
Awell Score is a microservice and API developed by the Awell team used to calculate validated scores for clinical and patient-reported outcome measures or perform other clinical algorithms. The API currently has a library of over 100 validated scores.
It was initially developed as an in-house microservice used by our products.
With Awell Score, you can avoid building clinical score calculations yourself which has a couple of benefits:
- ⏱️ Save time and resources. There's no longer a need to build these scoring algorithms yourself, which can be a time-consuming process.
- 📏 Reliability & validity. Score calculations can be openly peer-reviewed and clinically assured, resulting in a higher level of scrutiny and verifiability.
- 🧑🤝🧑 Contributions. Clinicians, developers, health care organizations, ... can contribute knowledge to a single, shared knowledgebase.
- Background
- Documentation
- Installation and running the app
- Test suite
- License policy
- How to Contribute
Patient-Reported Outcome Measures (PROMs) and clinical scores are commonly utilized to evaluate patients' health conditions. Platforms like MDCalc provide access to numerous such assessments through a user interface (UI). However, a UI is not practical for integrating these score calculations within your proprietary software systems. An API would be more appropriate, allowing these calculations to be embedded directly into your software.
Documentation for Awell Score can be found on Awell's Developer hub.
The API runs on Node and is built with Express and Typescript. NPM is used as the package manager. The API needs to be connected to a MongoDb database as it writes request logs and calculation results into it.
Installation guide:
- Run
npm ito install all the packages. - Create an
.envfile at the root of the project. Have a look at.env.examplefor the variables you need to run the app. - Ensure MongoDB is running on your machine (see instructions below).
- Run the app via the
npm run devcommand.
- Installation instructions for Mac
- Installation instructions for Windows
- Installation instructions for Ubuntu
All calculations are covered with an extensive test suite to ensure reliable and valid results.
Run all tests via the npm run test command.
This open-source library supports calculations for various clinical questionnaires, some of which may have licensing requirements. Users are responsible for ensuring they have the appropriate licenses to use these questionnaires. We do not provide or manage licenses for you to use the questionnaires. Failure to secure necessary licenses or comply with their terms is solely the user's liability.
Please ensure you have all necessary permissions before using this library.
We want to make contributing to this project as easy and transparent as possible, and we are grateful to the community for contributing bug fixes and improvements. You can read below to learn how you can take part in improving Awell Score.
The first version of the API—which was only used by Awell internally—was built in December 2020 with JavaScript and Flow for static type checking. When we decided to make the API publicly available, we migrated the app to Typescript
However, not all code passed Typescript's validation, and quite a few //@ts-expect-error comments had to be added in several places. Removing all of the errors will take some time and will be a gradual and progressive effort. Given the extensive test coverage, there's a high confidence that there's no impact on the reliability and validity of scores.
Awell Score was made possible by the following people:
 Nick Hellemans |