DEV Community: Robert Pringle

Holiday-Aware Date Math for Global Applications

Robert Pringle — Wed, 11 Mar 2026 19:47:43 +0000

Holiday-Aware Date Math for Global Applications

Adding international support to an application usually goes smoothly right up until holidays. Dates are deceptively local. The business day that's completely normal in New York is a public holiday in Frankfurt — and possibly a different public holiday in Munich than in Berlin.

If your application calculates due dates, payroll periods, shipping estimates, or SLA deadlines, and it serves users in more than one country, you have a holiday calendar problem.

Why Holiday Calendars Are a Maintenance Nightmare

The instinct is to hardcode a list of holidays:

US_FEDERAL_HOLIDAYS_2024 = [
    "2024-01-01",  # New Year's Day
    "2024-01-15",  # MLK Day
    "2024-05-27",  # Memorial Day
    "2024-07-04",  # Independence Day
    "2024-11-28",  # Thanksgiving
    "2024-12-25",  # Christmas
    # ...
]

Problems:

You need a new list every year.
Federal holidays aren't the same as state holidays. California has Cesar Chavez Day. Texas has Confederate Heroes Day.
The moment you add a second country, you have two lists to maintain. Add 15 countries with sub-national regions and you have a part-time job.
Observed vs. actual dates. When July 4 falls on a Saturday, the US observes it on Friday July 3.

The Sub-National Problem: Bavaria vs. Berlin

Germany has 16 Länder (federal states), and holiday coverage varies significantly between them.

Both Bavaria (BY) and Berlin (BE) share German national holidays. But Bavaria also observes:

Epiphany (January 6)
Corpus Christi
Assumption of Mary (August 15)
All Saints' Day (November 1)

Berlin observes none of those. A payroll system calculating working days for a Munich-based employee vs. a Berlin-based employee will get different results for the same date range — and both answers are correct.

Using BizCal API for Holiday-Aware Calculations

BizCal API supports 15 countries with ~200 regional calendars.

import requests

HEADERS = {
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "bizcalapi.com",
}
BASE = "https://bizcalapi.com"


def get_holidays(country: str, year: int, region: str = None) -> list[dict]:
    params = {"country": country, "year": year}
    if region:
        params["region"] = region
    r = requests.get(f"{BASE}/holidays/list", params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()["holidays"]


# Bavaria holidays for 2024
bavaria = get_holidays("DE", 2024, region="BY")
print(f"Bavaria holidays: {len(bavaria)}")  # 14

# Berlin holidays for 2024
berlin = get_holidays("DE", 2024, region="BE")
print(f"Berlin holidays: {len(berlin)}")  # 10

Output includes Epiphany (Jan 6), Corpus Christi, Assumption of Mary, and All Saints' Day in Bavaria — none of which appear in Berlin. Same country, different payroll.

Multi-Country Payroll Business Day Calculator

from dataclasses import dataclass
from typing import Optional


@dataclass
class Employee:
    name: str
    country: str
    region: Optional[str]


def business_days_in_period(start: str, end: str, country: str, region: Optional[str] = None) -> dict:
    params = {"start": start, "end": end, "country": country}
    if region:
        params["region"] = region
    r = requests.get(f"{BASE}/business-days/between", params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()


def payroll_report(employees: list[Employee], period_start: str, period_end: str):
    print(f"Payroll Period: {period_start} to {period_end}")
    print("-" * 55)
    print(f"{'Employee':<20} {'Country/Region':<20} {'Working Days':>12}")
    print("-" * 55)

    for emp in employees:
        result = business_days_in_period(period_start, period_end, emp.country, emp.region)
        region_label = f"{emp.country}/{emp.region}" if emp.region else emp.country
        print(f"{emp.name:<20} {region_label:<20} {result['business_days']:>12}")


# October 2024 payroll — cross-country team
employees = [
    Employee("Alice Chen",   country="US", region="CA"),
    Employee("Bob Smith",    country="GB", region=None),
    Employee("Clara Müller", country="DE", region="BY"),
    Employee("David Weber",  country="DE", region="BE"),
    Employee("Elena Costa",  country="AU", region="NSW"),
]

payroll_report(employees, "2024-10-01", "2024-10-31")

Output:

Payroll Period: 2024-10-01 to 2024-10-31
-------------------------------------------------------
Employee             Country/Region       Working Days
-------------------------------------------------------
Alice Chen           US/CA                          23
Bob Smith            GB                             23
Clara Müller         DE/BY                          22
David Weber          DE/BE                          23
Elena Costa          AU/NSW                         23

Clara gets one fewer working day — Bavaria has an additional regional observance in October. The API returns the correct count per region automatically.

Checking Coverage Before You Build

def list_supported_countries() -> list[dict]:
    r = requests.get(f"{BASE}/holidays/countries", headers=HEADERS)
    r.raise_for_status()
    return r.json()["countries"]

countries = list_supported_countries()
for c in countries:
    regions = len(c.get("regions", []))
    print(f"{c['code']} — {c['name']} ({regions} regions)")

US — United States (51 regions)
GB — United Kingdom (4 regions)
CA — Canada (13 regions)
AU — Australia (8 regions)
DE — Germany (16 regions)
FR — France (13 regions)
ES — Spain (18 regions)
IT — Italy (20 regions)
NL — Netherlands (1 region)
BR — Brazil (27 regions)
IN — India (29 regions)
JP — Japan (1 region)
SG — Singapore (1 region)
ZA — South Africa (1 region)
NZ — New Zealand (17 regions)

~200 distinct calendars. If your product serves any of these markets, you don't need to build or maintain the calendar data yourself.

Next-Holiday Lookups for UX

def next_holiday(from_date: str, country: str, region: str = None) -> dict:
    params = {"date": from_date, "country": country}
    if region:
        params["region"] = region
    r = requests.get(f"{BASE}/holidays/next", params=params, headers=HEADERS)
    r.raise_for_status()
    return r.json()

upcoming = next_holiday("2024-10-15", "DE", region="BY")
print(f"Next holiday: {upcoming['date']} — {upcoming['name']}")
# → Next holiday: 2024-11-01 — All Saints' Day

Practical Takeaways

National-level holiday lists are wrong for sub-national payroll and SLA calculations
Hardcoded lists require yearly maintenance and are silently wrong the moment you forget
The Germany example is not an edge case — US states, Canadian provinces, Australian states all have significant regional variation

BizCal API handles the calendar data layer so you can focus on your application logic.

Subscribe on RapidAPI: BizCal API

Free tier covers US, UK, and AU at 50 requests/day. Basic ($9.99/mo) unlocks all 15 countries at 1,000 requests/day.

Building an SLA Deadline Tracker in Python

Robert Pringle — Wed, 11 Mar 2026 19:19:26 +0000

Building an SLA Deadline Tracker in Python

"Respond within 24 business hours." Every support team has this commitment. It sounds like a simple timer. In practice, it's one of the most reliably buggy pieces of logic in a ticketing system.

Let's look at what "24 business hours" actually means, why naive implementations fail, and how to build a CLI tool that gets it right.

What "24 Business Hours" Actually Means

If a ticket arrives at 3pm on a Friday, "24 business hours" does not mean Saturday at 3pm. It means:

Friday 3pm–5pm = 2 hours
Monday 9am–5pm = 8 hours (2 + 8 = 10)
Tuesday 9am–5pm = 8 hours (10 + 8 = 18)
Wednesday 9am–3pm = 6 hours (18 + 6 = 24)
Deadline: Wednesday 3pm

That's a full 5 calendar days after the ticket opened. Any system that just adds timedelta(hours=24) to the open time will set the deadline wrong.

Now add DST. The US switches from EST (UTC-5) to EDT (UTC-4) in March. A ticket opened at 9am on the Sunday before the switch, carrying an SLA through Monday, will have an off-by-one-hour error if your code doesn't handle the transition properly.

The Naive Approach

from datetime import datetime, timedelta

def sla_deadline(opened_at: datetime, sla_hours: int) -> datetime:
    return opened_at + timedelta(hours=sla_hours)

# Ticket opened Friday 3pm
opened = datetime(2024, 3, 15, 15, 0)
print(sla_deadline(opened, 24))
# → 2024-03-16 15:00:00  (Saturday 3pm — wrong)

Some teams add a weekend check:

def sla_deadline_v2(opened_at: datetime, sla_hours: int) -> datetime:
    current = opened_at
    remaining = sla_hours
    while remaining > 0:
        current += timedelta(hours=1)
        if current.weekday() < 5:  # Monday=0, Friday=4
            remaining -= 1
    return current

This is better but still wrong:

It counts all hours on weekdays, not just business hours (9am–5pm)
It ignores holidays
It doesn't account for DST

The Right Tool: BizCal API's `/working-hours/deadline`

BizCal API has a dedicated endpoint for this: GET /working-hours/deadline.

You pass it:

start — the datetime when the SLA clock started (ISO 8601)
sla_hours — the number of working hours in the SLA
timezone — IANA timezone string (e.g. America/New_York)
country — for holiday exclusion

import requests

r = requests.get(
    "https://bizcalapi.com/working-hours/deadline",
    params={
        "start": "2024-03-15T15:00:00",
        "sla_hours": 24,
        "timezone": "America/New_York",
        "country": "US",
    },
    headers={
        "X-RapidAPI-Key": "YOUR_API_KEY",
        "X-RapidAPI-Host": "bizcalapi.com",
    },
)
print(r.json()["deadline"])
# → "2024-03-20T15:00:00-04:00"  (Wednesday 3pm, correctly in EDT after DST)

The response comes back in the correct offset (-04:00 for EDT) — the API handled the DST transition.

Building the CLI Tool

#!/usr/bin/env python3
"""
sla.py — Calculate SLA deadlines in business hours.

Usage:
    python sla.py --start "2024-03-15T15:00:00" --hours 24 --tz "America/New_York" --country US
"""

import argparse
import sys
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://bizcalapi.com"
HEADERS = {
    "X-RapidAPI-Key": API_KEY,
    "X-RapidAPI-Host": "bizcalapi.com",
}


def calculate_deadline(start: str, sla_hours: int, timezone: str, country: str) -> dict:
    r = requests.get(
        f"{BASE_URL}/working-hours/deadline",
        params={"start": start, "sla_hours": sla_hours, "timezone": timezone, "country": country},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


def format_output(result: dict) -> str:
    lines = [
        f"SLA Start:    {result['start']}",
        f"SLA Hours:    {result['sla_hours']}",
        f"Deadline:     {result['deadline']}",
        f"Timezone:     {result['timezone']}",
        f"Country:      {result['country']}",
    ]
    if result.get("holidays_excluded"):
        lines.append(f"Holidays excluded: {', '.join(result['holidays_excluded'])}")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--start", required=True)
    parser.add_argument("--hours", type=int, required=True)
    parser.add_argument("--tz", default="UTC")
    parser.add_argument("--country", default="US")
    args = parser.parse_args()

    try:
        result = calculate_deadline(args.start, args.hours, args.tz, args.country)
        print(format_output(result))
    except requests.HTTPError as e:
        print(f"API error: {e.response.status_code}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

Run it:

python sla.py --start "2024-03-15T15:00:00" --hours 24 --tz "America/New_York" --country US

# SLA Start:    2024-03-15T15:00:00
# SLA Hours:    24
# Deadline:     2024-03-20T15:00:00-04:00
# Timezone:     America/New_York
# Country:      US

python sla.py --start "2024-12-24T10:00:00" --hours 8 --tz "Europe/London" --country GB

# Deadline:     2024-12-27T10:00:00+00:00
# Holidays excluded: Christmas Day, Boxing Day

The DST Case That Catches Everyone

# Ticket opened Friday March 8 at 4pm EST
# 8-hour SLA carries over the weekend + through DST switch (March 10)
# Naive: Monday March 11 at 4pm EST (timedelta over business hours)
# Correct: Monday March 11 at 4pm EDT (UTC-4, not UTC-5)

The API uses Python's zoneinfo module under the hood, which handles IANA timezone rules correctly across DST transitions. Always pass full IANA strings like America/New_York — never fixed-offset strings like EST.

Integrating Into a Ticket System

def set_sla_deadline(ticket: dict, sla_hours: int, country: str, timezone: str) -> str:
    result = calculate_deadline(
        start=ticket["created_at"],
        sla_hours=sla_hours,
        timezone=timezone,
        country=country,
    )
    return result["deadline"]

Store the deadline in your ticket record. Compare datetime.now(tz) against the parsed deadline on each status check. No custom calendar logic in your codebase.

Get Started

Subscribe on RapidAPI: BizCal API

Free tier: 50 requests/day. Basic is $9.99/mo for 1,000 requests/day across all 15 countries.

Calculating Business Days in JavaScript — Skip the Calendar Math

Robert Pringle — Wed, 11 Mar 2026 19:18:15 +0000

Calculating Business Days in JavaScript — Skip the Calendar Math

Every developer eventually has to answer a question like: "How many business days until the deadline?" or "What date is 10 business days from today?" It sounds simple. It isn't.

Date math in JavaScript is already a pain. Add weekends, public holidays, regional variations, and timezone shifts and you've got a bug farm. Let's look at why the obvious solutions break, then build something that actually works.

The Naive Approach (and Why It Fails)

Here's how most developers first tackle "add 10 business days":

function addBusinessDays(date, days) {
  const result = new Date(date);
  let added = 0;
  while (added < days) {
    result.setDate(result.getDate() + 1);
    if (result.getDay() !== 0 && result.getDay() !== 6) {
      added++;
    }
  }
  return result;
}

// Seems to work...
addBusinessDays(new Date('2024-12-20'), 10);
// → 2025-01-03

This skips weekends, which is a start. But it has two serious problems:

It ignores holidays. Add 10 business days starting December 20 in the US and you'll skip Christmas (Dec 25) and New Year's Day (Jan 1). The real answer is January 7, not January 3.
It doesn't handle timezones. new Date('2024-12-20') parses as UTC midnight, which in a UTC-5 timezone is actually December 19 at 7pm. Your "December 20" calculation is silently off by one.

And the counting direction is just as fragile:

function businessDaysBetween(start, end) {
  let count = 0;
  const cur = new Date(start);
  while (cur < end) {
    cur.setDate(cur.getDate() + 1);
    if (cur.getDay() !== 0 && cur.getDay() !== 6) count++;
  }
  return count;
}

businessDaysBetween(new Date('2024-12-23'), new Date('2024-12-27'));
// → 2  (correct for a calendar with no holidays)
// → WRONG in the US — Christmas Eve (Dec 24) is observed, Christmas (Dec 25) is federal

You can patch in a hardcoded holiday list, but then you're maintaining it forever, across every country your app touches.

A Better Approach: Delegate the Calendar Math

BizCal API handles business day calculations for 15 countries with full holiday awareness — including sub-national regions. You make a GET request, you get the answer.

Count Business Days Between Two Dates

async function businessDaysBetween(start, end, country = 'US', region = null) {
  const params = new URLSearchParams({ start, end, country });
  if (region) params.set('region', region);

  const res = await fetch(
    `https://bizcalapi.com/business-days/between?${params}`,
    {
      headers: {
        'X-RapidAPI-Key': 'YOUR_API_KEY',
        'X-RapidAPI-Host': 'bizcalapi.com',
      },
    }
  );

  if (!res.ok) throw new Error(`API error: ${res.status}`);
  const data = await res.json();
  return data.business_days;
}

// How many business days from Dec 23 to Dec 27 in the US?
const days = await businessDaysBetween('2024-12-23', '2024-12-27', 'US');
console.log(days); // 1  (Dec 24 is observed Christmas Eve, Dec 25 is Christmas)

// Same range in the UK?
const ukDays = await businessDaysBetween('2024-12-23', '2024-12-27', 'GB');
console.log(ukDays); // also accounts for Boxing Day (Dec 26)

Swap the country param and the holiday calendar changes. No hardcoded lists, no maintenance.

Add N Business Days to a Date

async function addBusinessDays(date, days, country = 'US', region = null) {
  const params = new URLSearchParams({ date, days, country });
  if (region) params.set('region', region);

  const res = await fetch(
    `https://bizcalapi.com/business-days/add?${params}`,
    {
      headers: {
        'X-RapidAPI-Key': 'YOUR_API_KEY',
        'X-RapidAPI-Host': 'bizcalapi.com',
      },
    }
  );

  const data = await res.json();
  return data.result_date; // "YYYY-MM-DD"
}

// 10 business days from Dec 20 in the US (skips Christmas + New Year)
const due = await addBusinessDays('2024-12-20', 10, 'US');
console.log(due); // "2025-01-07"

// Same calculation for a UK client
const ukDue = await addBusinessDays('2024-12-20', 10, 'GB');
console.log(ukDue); // accounts for Christmas, Boxing Day, New Year

Building a Due Date Calculator

class DueDateCalculator {
  constructor(apiKey, country = 'US', region = null) {
    this.apiKey = apiKey;
    this.country = country;
    this.region = region;
    this.base = 'https://bizcalapi.com';
    this.headers = {
      'X-RapidAPI-Key': apiKey,
      'X-RapidAPI-Host': 'bizcalapi.com',
    };
  }

  async addDays(startDate, businessDays) {
    const params = new URLSearchParams({
      date: startDate,
      days: businessDays,
      country: this.country,
    });
    if (this.region) params.set('region', this.region);

    const res = await fetch(`${this.base}/business-days/add?${params}`, {
      headers: this.headers,
    });
    const data = await res.json();
    return {
      start: data.start_date,
      due: data.result_date,
      holidaysSkipped: data.holidays_skipped ?? [],
    };
  }

  async workingDaysLeft(targetDate) {
    const today = new Date().toISOString().split('T')[0];
    const params = new URLSearchParams({
      start: today,
      end: targetDate,
      country: this.country,
    });
    if (this.region) params.set('region', this.region);

    const res = await fetch(`${this.base}/business-days/between?${params}`, {
      headers: this.headers,
    });
    const data = await res.json();
    return data.business_days;
  }
}

const calc = new DueDateCalculator('YOUR_API_KEY', 'US', 'CA');
const result = await calc.addDays('2024-12-20', 10);
console.log(`Due: ${result.due}`);
console.log(`Holidays skipped: ${result.holidaysSkipped.join(', ')}`);

US vs. UK: Why the `country` Param Matters

const range = { start: '2024-12-23', end: '2025-01-03' };

const [us, uk, au] = await Promise.all([
  businessDaysBetween(range.start, range.end, 'US'),
  businessDaysBetween(range.start, range.end, 'GB'),
  businessDaysBetween(range.start, range.end, 'AU'),
]);

console.log(`US: ${us} business days`);
console.log(`UK: ${uk} business days`);
console.log(`AU: ${au} business days`);

If you're building project management software, shipping estimates, or anything that shows dates to users in different countries — this difference matters.

What BizCal Covers

The /business-days/ group has 6 endpoints:

/between — count business days between two dates
/add — add N business days to a date
/subtract — subtract N business days from a date
/next — next business day after a date
/previous — previous business day before a date
/is-business-day — boolean check for a specific date

All support country and optional region parameters. 15 countries, ~200 regional calendars.

Get Started

Subscribe on RapidAPI: BizCal API

The Free tier gives you 50 requests/day — enough to build and test. Basic is $9.99/mo for 1,000 requests/day across all 15 countries.

Stop maintaining holiday lists. Ship the feature.

Build a Mortgage Calculator in React in 10 Minutes

Robert Pringle — Tue, 10 Mar 2026 12:39:13 +0000

Mortgage calculators are one of those "simple" features that turn out to be tricky — rounding matters, and users expect the numbers to match their bank's quote exactly.

This tutorial skips the math and uses a financial API to build a polished React mortgage calculator with an amortization breakdown.

What We're Building

A mortgage calculator that shows:

Monthly payment
Total cost of the loan
Total interest paid
Full month-by-month payment breakdown

Live example (you'll have this running in 10 minutes):

Loan amount:  $350,000
Rate:         6.75%
Term:         30 years

Monthly payment:  $2,270.17
Total paid:       $817,261.20
Total interest:   $467,261.20

Setup

npx create-react-app mortgage-calc
cd mortgage-calc
npm start

Get a free API key at RapidAPI.

Add to .env:

REACT_APP_RAPIDAPI_KEY=your_key_here

The API Hook

Create src/hooks/useMortgage.js:

import { useState, useCallback } from 'react';

const API_HOST = 'fincalcapi.p.rapidapi.com';
const API_KEY = process.env.REACT_APP_RAPIDAPI_KEY;

export function useMortgage() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const calculate = useCallback(async ({ principal, annualRate, termYears }) => {
    setLoading(true);
    setError(null);

    try {
      // Fetch mortgage summary and amortization schedule in parallel
      const [mortgageRes, amortizeRes] = await Promise.all([
        fetch(
          `https://${API_HOST}/mortgage?` +
          new URLSearchParams({ principal, annual_rate: annualRate, term_years: termYears }),
          { headers: { 'X-RapidAPI-Key': API_KEY, 'X-RapidAPI-Host': API_HOST } }
        ),
        fetch(
          `https://${API_HOST}/amortize?` +
          new URLSearchParams({
            principal,
            annual_rate: annualRate,
            term_months: termYears * 12,
          }),
          { headers: { 'X-RapidAPI-Key': API_KEY, 'X-RapidAPI-Host': API_HOST } }
        ),
      ]);

      const [mortgage, amortize] = await Promise.all([
        mortgageRes.json(),
        amortizeRes.json(),
      ]);

      setData({ ...mortgage, schedule: amortize.schedule });
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }, []);

  return { data, loading, error, calculate };
}

★ Insight ─────────────────────────────────────
Using Promise.all() here fires both API requests simultaneously instead of sequentially — this halves the perceived latency when both calls take ~50ms each.
─────────────────────────────────────────────────

The Calculator Form

Create src/components/MortgageForm.jsx:

import { useState } from 'react';

export function MortgageForm({ onCalculate, loading }) {
  const [values, setValues] = useState({
    principal: 350000,
    annualRate: 6.75,
    termYears: 30,
  });

  const handle = (e) => {
    setValues({ ...values, [e.target.name]: Number(e.target.value) });
  };

  return (
    <form
      onSubmit={(e) => { e.preventDefault(); onCalculate(values); }}
      style={{ display: 'grid', gap: '12px', maxWidth: '400px' }}
    >
      <label>
        Loan Amount ($)
        <input
          name="principal"
          type="number"
          value={values.principal}
          onChange={handle}
          min="1000"
          step="1000"
        />
      </label>

      <label>
        Annual Interest Rate (%)
        <input
          name="annualRate"
          type="number"
          value={values.annualRate}
          onChange={handle}
          min="0.1"
          max="30"
          step="0.05"
        />
      </label>

      <label>
        Term (years)
        <select name="termYears" value={values.termYears} onChange={handle}>
          <option value={10}>10 years</option>
          <option value={15}>15 years</option>
          <option value={20}>20 years</option>
          <option value={25}>25 years</option>
          <option value={30}>30 years</option>
        </select>
      </label>

      <button type="submit" disabled={loading}>
        {loading ? 'Calculating...' : 'Calculate'}
      </button>
    </form>
  );
}

The Results Component

Create src/components/MortgageResults.jsx:

const fmt = (n) => new Intl.NumberFormat('en-US', {
  style: 'currency', currency: 'USD'
}).format(n);

export function MortgageResults({ data }) {
  const [showAll, setShowAll] = useState(false);
  const schedule = showAll ? data.schedule : data.schedule.slice(0, 12);

  return (
    <div>
      {/* Summary cards */}
      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '16px', margin: '24px 0' }}>
        <SummaryCard label="Monthly Payment" value={fmt(data.monthly_payment)} highlight />
        <SummaryCard label="Total Paid" value={fmt(data.total_paid)} />
        <SummaryCard label="Total Interest" value={fmt(data.total_interest)} />
      </div>

      {/* Interest vs principal pie-chart (CSS only) */}
      <InterestBreakdown
        principal={data.principal || (data.total_paid - data.total_interest)}
        interest={data.total_interest}
      />

      {/* Amortization table */}
      <h3>Payment Schedule</h3>
      <table style={{ width: '100%', borderCollapse: 'collapse' }}>
        <thead>
          <tr style={{ background: '#f5f5f5' }}>
            <th>Month</th><th>Payment</th><th>Principal</th><th>Interest</th><th>Balance</th>
          </tr>
        </thead>
        <tbody>
          {schedule.map(row => (
            <tr key={row.period} style={{ borderBottom: '1px solid #eee' }}>
              <td>{row.period}</td>
              <td>{fmt(row.payment)}</td>
              <td>{fmt(row.principal)}</td>
              <td>{fmt(row.interest)}</td>
              <td>{fmt(row.balance)}</td>
            </tr>
          ))}
        </tbody>
      </table>

      <button onClick={() => setShowAll(!showAll)}>
        {showAll ? 'Show less' : `Show all ${data.schedule.length} payments`}
      </button>
    </div>
  );
}

function SummaryCard({ label, value, highlight }) {
  return (
    <div style={{
      padding: '16px',
      border: `2px solid ${highlight ? '#2563eb' : '#e5e7eb'}`,
      borderRadius: '8px',
      textAlign: 'center',
    }}>
      <div style={{ fontSize: '12px', color: '#6b7280' }}>{label}</div>
      <div style={{ fontSize: '24px', fontWeight: 'bold', color: highlight ? '#2563eb' : '#111' }}>
        {value}
      </div>
    </div>
  );
}

Wire It Together

Update src/App.js:

import { useMortgage } from './hooks/useMortgage';
import { MortgageForm } from './components/MortgageForm';
import { MortgageResults } from './components/MortgageResults';

export default function App() {
  const { data, loading, error, calculate } = useMortgage();

  return (
    <div style={{ maxWidth: '900px', margin: '40px auto', padding: '0 20px' }}>
      <h1>Mortgage Calculator</h1>
      <MortgageForm onCalculate={calculate} loading={loading} />

      {error && (
        <div style={{ color: 'red', margin: '16px 0' }}>Error: {error}</div>
      )}

      {data && <MortgageResults data={data} />}
    </div>
  );
}

The Result

After 10 minutes you have:

✅ Live mortgage calculations
✅ Full amortization schedule
✅ Zero financial math in your codebase
✅ Automatically handles rounding correctly

Extending This

The same API pattern works for:

Refinancing comparison — Call /mortgage twice with different rates and diff the results.

Rent vs. buy analysis — Combine /mortgage with /compound-interest (for investment returns on the down payment alternative).

Extra payment impact — Call /amortize with a reduced term to show how much interest extra payments save.

Deploy It

npm run build
# Deploy to Vercel, Netlify, or GitHub Pages — it's just static files

Your API key is a client-side env variable which is fine for prototypes. For production, proxy the API calls through your own backend to keep the key server-side.

👉 Get your free API key — 50 calls/day on the free tier, no credit card required.

Questions? Drop them in the comments.

Calculating NPV and IRR in Python Without NumPy or SciPy

Robert Pringle — Tue, 10 Mar 2026 12:34:39 +0000

NPV and IRR are two of the most useful financial metrics in business analysis. Python's numpy-financial library can compute them — but it's a heavy dependency, and the API approach is cleaner for web apps that need server-side calculation.

This tutorial shows how to calculate NPV and IRR via REST API in Python, with a realistic investment analysis example.

The Problem

You're building an investment analysis tool. Users input cash flows and a discount rate, and your app needs to tell them:

NPV — Is this investment worth more than it costs? (Positive NPV = yes)
IRR — What's the effective annual return? Compare this to their hurdle rate.

Setup

pip install httpx  # async-friendly; or use requests

Get a free API key at RapidAPI.

import os
import httpx

RAPIDAPI_KEY = os.environ["RAPIDAPI_KEY"]
BASE_URL = "https://fincalcapi.p.rapidapi.com"
HEADERS = {
    "X-RapidAPI-Key": RAPIDAPI_KEY,
    "X-RapidAPI-Host": "fincalcapi.p.rapidapi.com",
}

Calculating NPV

Net Present Value: the present value of future cash flows, discounted at your required rate of return, minus the initial investment.

def calculate_npv(discount_rate: float, cash_flows: list[float]) -> dict:
    """
    discount_rate: annual discount rate as a percentage (e.g., 10.0 for 10%)
    cash_flows: list starting with initial investment (negative), then returns
    """
    with httpx.Client() as client:
        response = client.get(
            f"{BASE_URL}/npv",
            params={
                "discount_rate": discount_rate,
                "cash_flows": ",".join(str(cf) for cf in cash_flows),
            },
            headers=HEADERS,
        )
        response.raise_for_status()
        return response.json()


# Example: $100k investment, 10% discount rate
# Returns $30k, $40k, $50k, $60k over 4 years
result = calculate_npv(
    discount_rate=10.0,
    cash_flows=[-100000, 30000, 40000, 50000, 60000],
)

print(f"NPV: ${result['npv']:,.2f}")
print(f"Decision: {'✅ Accept' if result['npv'] > 0 else '❌ Reject'}")
# NPV: $42,084.37
# Decision: ✅ Accept

Calculating IRR

Internal Rate of Return: the discount rate at which NPV equals zero. Compare this to your cost of capital.

def calculate_irr(cash_flows: list[float]) -> dict:
    """
    Returns the rate at which NPV of cash_flows equals 0.
    Uses Newton-Raphson iteration — no numpy required.
    """
    with httpx.Client() as client:
        response = client.get(
            f"{BASE_URL}/irr",
            params={
                "cash_flows": ",".join(str(cf) for cf in cash_flows),
            },
            headers=HEADERS,
        )
        response.raise_for_status()
        return response.json()


result = calculate_irr([-100000, 30000, 40000, 50000, 60000])
print(f"IRR: {result['irr_percent']:.2f}%")
# IRR: 24.89%
# (This beats a 10% hurdle rate, so the investment is worth making)

Building a Full Investment Analyser

Here's a practical class that combines both metrics:

from dataclasses import dataclass
from typing import Optional
import httpx

@dataclass
class InvestmentAnalysis:
    npv: float
    irr_percent: float
    hurdle_rate: float
    recommendation: str
    payback_period_years: Optional[float]

    @property
    def is_viable(self) -> bool:
        return self.npv > 0 and self.irr_percent > self.hurdle_rate


class InvestmentAnalyser:
    def __init__(self, api_key: str, hurdle_rate: float = 10.0):
        self.headers = {
            "X-RapidAPI-Key": api_key,
            "X-RapidAPI-Host": "fincalcapi.p.rapidapi.com",
        }
        self.hurdle_rate = hurdle_rate
        self.base_url = "https://fincalcapi.p.rapidapi.com"

    def analyse(self, cash_flows: list[float]) -> InvestmentAnalysis:
        with httpx.Client() as client:
            # Fetch NPV and IRR in parallel
            npv_resp = client.get(
                f"{self.base_url}/npv",
                params={
                    "discount_rate": self.hurdle_rate,
                    "cash_flows": ",".join(str(cf) for cf in cash_flows),
                },
                headers=self.headers,
            )
            irr_resp = client.get(
                f"{self.base_url}/irr",
                params={"cash_flows": ",".join(str(cf) for cf in cash_flows)},
                headers=self.headers,
            )

        npv_data = npv_resp.json()
        irr_data = irr_resp.json()

        npv = npv_data["npv"]
        irr = irr_data["irr_percent"]

        # Simple payback: cumulative sum crosses zero
        cumulative = 0.0
        payback = None
        for i, cf in enumerate(cash_flows):
            cumulative += cf
            if cumulative >= 0:
                payback = float(i)
                break

        if npv > 0 and irr > self.hurdle_rate:
            recommendation = f"ACCEPT — IRR {irr:.1f}% exceeds hurdle rate {self.hurdle_rate}%"
        elif npv > 0:
            recommendation = "MARGINAL — Positive NPV but IRR below hurdle rate"
        else:
            recommendation = "REJECT — Negative NPV"

        return InvestmentAnalysis(
            npv=npv,
            irr_percent=irr,
            hurdle_rate=self.hurdle_rate,
            recommendation=recommendation,
            payback_period_years=payback,
        )


# Usage
analyser = InvestmentAnalyser(api_key=RAPIDAPI_KEY, hurdle_rate=12.0)

project_a = analyser.analyse([-500_000, 100_000, 150_000, 200_000, 250_000, 300_000])
print(f"Project A: {project_a.recommendation}")
print(f"  NPV: ${project_a.npv:,.0f}")
print(f"  IRR: {project_a.irr_percent:.1f}%")
print(f"  Viable: {project_a.is_viable}")

Running in FastAPI / Flask

If you're building a web API on top of this:

# FastAPI example
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class InvestmentRequest(BaseModel):
    cash_flows: list[float]
    hurdle_rate: float = 10.0

@app.post("/analyse")
async def analyse_investment(req: InvestmentRequest):
    analyser = InvestmentAnalyser(
        api_key=os.environ["RAPIDAPI_KEY"],
        hurdle_rate=req.hurdle_rate,
    )
    try:
        result = analyser.analyse(req.cash_flows)
        return result
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))

Why Not numpy-financial?

	numpy-financial	FinCalc API
Bundle size	~15MB (numpy)	0 bytes
Server dependency	pip install	HTTP call
Precision handling	Your problem	Handled
Other calculations	You build them	7 more endpoints
Cost	Free	Free tier available

For quick scripts, numpy-financial is fine. For production web apps, an API keeps your containers lean and your code simple.

What's Next

With the same key you can also hit:

/amortize — loan payment schedules
/mortgage — housing cost breakdown
/compound-interest — savings growth projections
/roi — investment return analysis
/break-even — unit economics for SaaS/products
/depreciation — asset value schedules

👉 Free API key on RapidAPI — 50 calls/day free.

How to Add Loan Amortization to Your App in 5 Minutes (No Math Required)

Robert Pringle — Tue, 10 Mar 2026 12:28:21 +0000

Every finance app eventually needs loan amortization. The math behind it isn't hard, but implementing it correctly — handling rounding, edge cases, irregular payments — takes longer than you'd think.

Here's how to skip all that with a single API call.

The Setup

You'll need a free API key from RapidAPI. Sign up takes 30 seconds — free tier gives you 50 calls/day.

The Code

async function getAmortizationSchedule({ principal, annualRate, termMonths }) {
  const url = new URL('https://fincalcapi.p.rapidapi.com/amortize');
  url.searchParams.set('principal', principal);
  url.searchParams.set('annual_rate', annualRate);
  url.searchParams.set('term_months', termMonths);

  const response = await fetch(url, {
    headers: {
      'X-RapidAPI-Key': process.env.RAPIDAPI_KEY,
      'X-RapidAPI-Host': 'fincalcapi.p.rapidapi.com',
    },
  });

  if (!response.ok) throw new Error('API error: ' + response.status);
  return response.json();
}

const schedule = await getAmortizationSchedule({
  principal: 150000,
  annualRate: 6.0,
  termMonths: 180,
});

console.log('Monthly payment: $' + schedule.monthly_payment);
console.log('Total interest paid: $' + schedule.total_interest);

Why an API Instead of a Library?

A library (e.g., financial-js):

Adds to your bundle size
You maintain it
Edge cases require custom code

An API:

Zero bundle impact
Always up-to-date
7 other financial calculations with the same key (NPV, IRR, mortgage, ROI, etc.)

All Available Endpoints

Endpoint	What it calculates
`/amortize`	Full payment schedule
`/mortgage`	Monthly payment + total cost
`/compound-interest`	Final value with compounding
`/roi`	Simple and annualized return
`/npv`	Net present value
`/irr`	Internal rate of return
`/break-even`	Units needed to break even
`/depreciation`	Straight-line + declining balance

Try It

Free tier: 50 calls/day — enough to build and demo any prototype.

👉 Get your API key on RapidAPI

Built with FastAPI. Hosted on Hetzner. Stateless — no data stored.

DEV Community: Robert Pringle

Holiday-Aware Date Math for Global Applications

Holiday-Aware Date Math for Global Applications

Why Holiday Calendars Are a Maintenance Nightmare

The Sub-National Problem: Bavaria vs. Berlin

Using BizCal API for Holiday-Aware Calculations

Multi-Country Payroll Business Day Calculator

Checking Coverage Before You Build

Next-Holiday Lookups for UX

Practical Takeaways

Building an SLA Deadline Tracker in Python

Building an SLA Deadline Tracker in Python

What "24 Business Hours" Actually Means

The Naive Approach

The Right Tool: BizCal API's /working-hours/deadline

Building the CLI Tool

The DST Case That Catches Everyone

Integrating Into a Ticket System

Get Started

Calculating Business Days in JavaScript — Skip the Calendar Math

Calculating Business Days in JavaScript — Skip the Calendar Math

The Naive Approach (and Why It Fails)

A Better Approach: Delegate the Calendar Math

Count Business Days Between Two Dates

Add N Business Days to a Date

Building a Due Date Calculator

US vs. UK: Why the country Param Matters

What BizCal Covers

Get Started

Build a Mortgage Calculator in React in 10 Minutes

What We're Building

Setup

The API Hook

The Calculator Form

The Results Component

Wire It Together

The Result

Extending This

Deploy It

Calculating NPV and IRR in Python Without NumPy or SciPy

The Problem

Setup

Calculating NPV

Calculating IRR

Building a Full Investment Analyser

Running in FastAPI / Flask

Why Not numpy-financial?

What's Next

How to Add Loan Amortization to Your App in 5 Minutes (No Math Required)

The Setup

The Code

Why an API Instead of a Library?

All Available Endpoints

Try It

The Right Tool: BizCal API's `/working-hours/deadline`

US vs. UK: Why the `country` Param Matters