Introduction
This documentation describes the API for our medication database, a core component of our new medical product designed to support physicians in prescribing medications accurately. The API provides a reliable and structured way for healthcare professionals to search for and select medications, tailored to meet specific regulatory and market requirements.
Our initial data source is an external service provider called Vidal. Vidal offers a data structure that organizes medication information into distinct layers. However, we discovered that their API often omits crucial details, leading us to import their raw data into our own system. By doing so, we can fill in missing links and enhance data quality, ensuring that the information available to physicians is both complete and consistent.
Entity Types
The data model we employ is inspired by Vidal’s format but has been modified for clarity and precision. To avoid the pitfalls associated with ambiguous abbreviations in code, we use explicit names for each layer:
Virtual Product
Represents the generic concept of a medication (for example, "Paracetamol 500 mg") without tying it to a specific manufacturer. A Virtual Product is associated with one or more molecules, which is essential for medications that contain multiple active ingredients—such as combination drugs like Piperacillin and Tazobactam. Each molecule connection includes dosage details, ensuring that the precise composition is clearly defined.
Actual Product
Contains detailed, manufacturer-specific information that links the generic Virtual Product to its real-world counterpart. This includes manufacturer details, specific formulations, and a clear association with the molecules and their dosages as defined in the Virtual Product.
Actual Product Package
Describes the physical packaging available for the medication, such as those dispensed at pharmacies. This layer not only captures the packaging details but also breaks down the contents into individual items. For example, a package might include a tablet, or in cases where the medication is a compound product, it could consist of a powder along with a solvent or even an additional item like an applicator.
ER Diagram
A unique aspect of our approach is the flexibility it offers. Although our primary focus is on the German market—where specific identifiers like the Pharmazentralnummer (PZN) play a critical role—the system is designed to accommodate the regulatory and practical requirements of other countries, such as Romania or the USA. Furthermore, by importing and standardizing the raw data from Vidal into our own database, we maintain the capability to integrate alternative data sources in the future. If a different provider offers more complete or higher-quality data, we can import and convert it into our standardized format with minimal disruption.
This API is intended to be robust, flexible, and scalable, ensuring that healthcare professionals have access to up-to-date and accurate medication information at all times. The following sections of this documentation will provide detailed guidance on how to interact with the API, including endpoint definitions, authentication mechanisms, and usage examples.