@fin.cx/fee-schedules

@fin.cx/fee-schedules is a TypeScript package for country-specific fee schedule data. It gives apps a clean, searchable source of truth for statutory, contractual, and professional fee schedules, starting with Germany's healthcare, legal, court, public compensation, and regulated professional service schedules.

Use it when you need stable identifiers, abbreviations, imported fee table rows, source metadata, and rule sections for fee systems such as GOÄ, GOZ, RVG, GNotKG, GKG, HOAI, JVEG, and more.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Installation

pnpm add @fin.cx/fee-schedules

Quick Start

import { FEE_SCHEDULE_CATALOGS, FeeSchedules, feeSchedules } from '@fin.cx/fee-schedules';

const schedules = new FeeSchedules();
const germanyCatalog = FEE_SCHEDULE_CATALOGS.find((catalog) => catalog.countryCode === 'DE');

const germany = schedules.getByCountry('DE');
const goae = schedules.findByAbbreviation('GOÄ');
const goaeNumber1 = schedules.getFeeRow('de-goae', '1');
const legalFeeRows = schedules.searchFeeRows('Einigungsgebühr', 'de-rvg');
const courtFees = feeSchedules.getById('de-gkg');

console.log(germanyCatalog?.schedules.length); // 21
console.log(goae?.description); // Gebührenordnung für Ärzte; privatärztliche Leistungen außerhalb GKV.
console.log(goaeNumber1?.cells); // ['1', 'Beratung - auch mittels Fernsprecher -', '80', '9,12']
console.log(legalFeeRows.map((item) => item.code));
console.log(courtFees?.area); // Gerichte allgemein
console.log(germany.map((item) => item.id));

What You Get

• Country catalogs with stable country codes and country names.
• Individual fee schedule records with stable IDs, abbreviations, areas, and short descriptions.
• Imported fee rows and rule sections for official federal XML schedules.
• Lookup helpers for country code, ID, abbreviation, fee code, and free-text search.
• A ready-to-use singleton (feeSchedules) and a configurable class (FeeSchedules) for custom catalogs.
• TypeScript interfaces exported directly from the package.

API

Exports

| Export | Description | | --- | --- | | FEE_SCHEDULE_DATA_URL | Raw code.foss.global URL used for startup data loading. | | feeSchedulePayload | Full remotely loaded payload. | | FEE_SCHEDULE_CATALOGS | All available country catalogs from the remotely loaded payload. | | FEE_SCHEDULE_DATA | Imported fee data, rule sections, source metadata, and import status from the remotely loaded payload. | | SUPPORTED_COUNTRY_CODES | Country codes derived from FEE_SCHEDULE_CATALOGS. | | loadFeeSchedulePayload(url?) | Loads and validates a fee schedule payload from a URL. | | FeeSchedules | Lookup/search class. Can be constructed with the default catalog/data lists or custom lists. | | feeSchedules | Default singleton instance of FeeSchedules. |

Methods

| Method | Description | | --- | --- | | getCountries() | Returns all loaded country catalogs. | | getByCountry(countryCode) | Returns schedules for a country code such as DE. Country lookup is case-insensitive. | | getById(id) | Returns the schedule with the exact stable ID, or undefined. | | getDataByScheduleId(scheduleId) | Returns imported source metadata, fee rows, rule sections, and data status. | | getFeeRows(scheduleId) | Returns all imported fee rows for a schedule. | | getFeeRow(scheduleId, code) | Returns the first imported coded fee row matching a schedule and code. | | getRuleSections(scheduleId) | Returns imported rule sections for a schedule. | | findByAbbreviation(abbreviation, countryCode?) | Returns the first schedule matching an abbreviation. Abbreviation lookup normalizes whitespace and casing. | | search(query, countryCode?) | Searches id, area, abbreviation, and description. Returns an empty array for empty queries. | | searchFeeRows(query, scheduleId?) | Searches imported fee rows and original source cells. | | searchRuleSections(query, scheduleId?) | Searches imported rule sections. |

Data Shape

export type TFeeScheduleCountryCode = string;

export interface IFeeSchedule {
  id: string;
  countryCode: TFeeScheduleCountryCode;
  area: string;
  abbreviation: string;
  description: string;
}

export interface ICountryFeeScheduleCatalog {
  countryCode: TFeeScheduleCountryCode;
  countryName: string;
  schedules: IFeeSchedule[];
}

export interface IFeeScheduleData {
  scheduleId: string;
  dataStatus: 'federal-law-fee-data' | 'federal-law-rules-only' | 'external-source-pending';
  edition: string;
  source: IFeeScheduleSource;
  feeRows: IFeeScheduleFeeRow[];
  ruleSections: IFeeScheduleRuleSection[];
  notes: string[];
}

export interface IFeeSchedulePayload {
  schemaVersion: number;
  generatedAt?: string;
  catalogs: ICountryFeeScheduleCatalog[];
  scheduleData: IFeeScheduleData[];
}

Fee rows preserve the original source cells in order. Where the row is code-based, code, description, points, and amountEur are populated when those values can be read directly from the source table.

const row = schedules.getFeeRow('de-goae', '1');

console.log(row?.cells);
// ['1', 'Beratung - auch mittels Fernsprecher -', '80', '9,12']

Data Sources

The package imports official federal XML data from gesetze-im-internet.de for these schedules: GOÄ, GOZ, GOP, GOT, StBVV, RVG, GNotKG, GKG, FamGKG, GvKostG, JVEG, InsVV, HOAI, and AMPreisV.

Some German fee schedules are not federal XML laws on gesetze-im-internet.de. They are represented with explicit external-source-pending source metadata until their source-specific importers are added: EBM, BEMA, aG-DRG / FPV, UV-GOÄ, Heilmittel GKV, Hebammenhilfevertrag, and GebüH.

Generated Files

The npm package does not ship the catalog or fee data payload. Supported countries, schedule metadata, generation source config, fee rows, and rule sections live under .onlygit/ in git.

Runtime startup loads the generated payload from:

https://code.foss.global/fin.cx/fee-schedules/raw/branch/main/.onlygit/fee-schedules.json

Maintainers regenerate the git-only JSON payload with:

pnpm run generate:germany

The generator lives in scripts/generate-germany.mjs. It reads .onlygit/fee-schedules.sources.json, downloads the official XML ZIP files into .nogit/fee-schedules-sources/, extracts them, parses fee table rows and rule sections, and writes:

.onlygit/fee-schedules.json

Germany Catalog

The initial catalog covers 21 German fee schedule systems.

| ID | Area | Abbreviation | Purpose | | --- | --- | --- | --- | | de-goae | Ärzte privat | GOÄ | Gebührenordnung für Ärzte; privatärztliche Leistungen außerhalb GKV. | | de-goz | Zahnärzte privat | GOZ | Gebührenordnung für Zahnärzte; privat-/selbst zu zahlende zahnärztliche Leistungen. | | de-gop | Psychotherapeuten privat | GOP | Gebührenordnung für Psychologische Psychotherapeuten und Kinder-/Jugendlichenpsychotherapeuten. | | de-ebm | Ärzte GKV | EBM | Einheitlicher Bewertungsmaßstab; Abrechnung von Vertragsärzten und Vertragspsychotherapeuten mit der GKV. | | de-bema | Zahnärzte GKV | BEMA | Bewertungsmaßstab zahnärztlicher Leistungen; GKV-Abrechnung in Zahnarztpraxen. | | de-ag-drg-fpv | Krankenhäuser | aG-DRG / FPV | Fallpauschalen-Katalog und Abrechnungsbestimmungen für stationäre Krankenhausfälle. | | de-uv-goae | Berufsgenossenschaft/Unfallversicherung | UV-GOÄ | Gebührenordnung für Ärzte im Bereich gesetzliche Unfallversicherung. | | de-got | Tierärzte | GOT | Gebührenordnung für Tierärztinnen und Tierärzte. | | de-stbvv | Steuerberater | StBVV | Steuerberatervergütungsverordnung; gesetzliche Vergütung für steuerberatende Vorbehaltsaufgaben. | | de-rvg | Rechtsanwälte | RVG | Rechtsanwaltsvergütungsgesetz mit Vergütungsverzeichnis. | | de-gnotkg | Notare / Grundbuch / Nachlass | GNotKG | Gerichts- und Notarkostengesetz; bundesweit einheitliche Notarkosten. | | de-gkg | Gerichte allgemein | GKG | Gerichtskostengesetz mit Kostenverzeichnis und Gebührentabellen. | | de-famgkg | Familiengericht | FamGKG | Gerichtskosten in Familiensachen. | | de-gvkostg | Gerichtsvollzieher | GvKostG | Gerichtsvollzieherkostengesetz mit Kostenverzeichnis. | | de-jveg | Sachverständige/Dolmetscher/Zeugen bei Gericht | JVEG | Justizvergütungs- und -entschädigungsgesetz. | | de-insvv | Insolvenzverwalter | InsVV | Insolvenzrechtliche Vergütungsverordnung. | | de-hoai | Architekten/Ingenieure | HOAI | Honorarordnung für Architekten und Ingenieure; heute vor allem Orientierungs-/Auffangsystem für erfasste Planungsleistungen. | | de-heilmittel-gkv | Heilmittel, z. B. Physio/Logo/Ergo | keine einzelne GO | GKV-Vergütungsvereinbarungen/Preislisten nach Bundesrahmenverträgen. | | de-hebammenhilfevertrag | Hebammen GKV | Hebammenhilfevertrag | Vertrag/Vergütungsvereinbarung nach § 134a SGB V. | | de-ampreisv | Apotheken/Rx-Arzneimittel | AMPreisV | Arzneimittelpreisverordnung; Preisbildung für verschreibungspflichtige Arzneimittel. | | de-gebueh | Heilpraktiker | GebüH | Gebührenverzeichnis für Heilpraktiker; keine amtliche verbindliche Gebührenordnung, eher Orientierung/übliche Vergütung. |

Typical Use Cases

• Build country-aware fee schedule selectors.
• Normalize German fee schedule abbreviations in forms and admin systems.
• Enrich billing, compliance, procurement, or legal-tech workflows with stable fee schedule metadata.
• Power search, autocomplete, or classification flows without hand-maintaining the same acronym list in every app.

Scope

This package includes imported fee rows and rule sections for the German federal schedules currently available as official XML. It does not yet normalize every schedule into a single calculation engine because several schedules use different fee mechanics: points, factors, euro amounts, value tables, formula rules, or external annual catalogs.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.