Skip to main content

Business Days Calculator API

REAL DATA

Add, count or inspect business days using verified national public-holiday rules for 61 countries, including observed substitute days.

Authoritative reference data or standards computation

Base URL
/api/business-days
Category
Date & Time
Capabilities
3 routes
Last updated
July 29, 2026
Data source
  • Computed from the platform's verified national public-holiday rules for 61 countries; each country's official statute or ministry page is cited by GET /api/holidays/countries

GET /api/business-days/add Add or subtract business days from a date

Live requestRuns against the public API
No key required
GET/api/business-days/add?country=US&start=2026-07-02&days=1

Request parameters

ISO 3166-1 alpha-2 country code. Supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA.

Starting UTC calendar date (2020–2052).

Signed number of business days to move (-2,600–2,600).

Count start as the first day when it is a business day. days=0 still returns start.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/business-days/add?country=US&start=2026-07-02&days=1"
const res = await fetch("https://randomapi.dev/api/business-days/add?country=US&start=2026-07-02&days=1");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/business-days/add?country=US&start=2026-07-02&days=1").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/business-days/add?country=US&start=2026-07-02&days=1"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 4
country string required

ISO 3166-1 alpha-2 country code. Supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA.

allowed: 2 – 2
example: country=US
start date required

Starting UTC calendar date (2020–2052).

example: start=2026-07-02
days int required

Signed number of business days to move (-2,600–2,600).

allowed: -2600 – 2600
example: days=1
includeStart boolean

Count start as the first day when it is a business day. days=0 still returns start.

default: false
example: includeStart=true
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryName
exclude list

Return all fields except these (comma-separated).

example: exclude=holidaysSkipped
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 9
country string

Canonical country code.

example: US

countryName string

English country name.

example: United States

start string (YYYY-MM-DD)

Starting date.

example: 2026-07-02

days integer

Signed requested business-day movement.

example: 1

includeStart boolean

Whether a business-day start was eligible to count.

example: false

result string (YYYY-MM-DD)

Resulting calendar date.

example: 2026-07-06

calendarDays integer

Signed calendar-day distance from start to result.

example: 4

weekendsSkipped integer

Weekend dates crossed and not counted.

example: 2

holidaysSkipped integer

Weekday public/observed holidays crossed and not counted.

example: 1

Documented examples

Build-generated requests and complete responses 3
Next US business day across observed July 4
GET /api/business-days/add?country=US&start=2026-07-02&days=1 
{
  "data": {
    "country": "US",
    "countryName": "United States",
    "start": "2026-07-02",
    "days": 1,
    "includeStart": false,
    "result": "2026-07-06",
    "calendarDays": 4,
    "weekendsSkipped": 2,
    "holidaysSkipped": 1
  },
  "meta": {
    "endpoint": "business-days",
    "route": "/add",
    "params": {
      "country": "US",
      "start": "2026-07-02",
      "days": 1,
      "includeStart": false
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Five Danish business days backwards
GET /api/business-days/add?country=DK&start=2026-04-07&days=-5 
{
  "data": {
    "country": "DK",
    "countryName": "Denmark",
    "start": "2026-04-07",
    "days": -5,
    "includeStart": false,
    "result": "2026-03-26",
    "calendarDays": -12,
    "weekendsSkipped": 4,
    "holidaysSkipped": 3
  },
  "meta": {
    "endpoint": "business-days",
    "route": "/add",
    "params": {
      "country": "DK",
      "start": "2026-04-07",
      "days": -5,
      "includeStart": false
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Count the start as day one
GET /api/business-days/add?country=GB&start=2026-06-10&days=3&includeStart=true 
{
  "data": {
    "country": "GB",
    "countryName": "United Kingdom",
    "start": "2026-06-10",
    "days": 3,
    "includeStart": true,
    "result": "2026-06-12",
    "calendarDays": 2,
    "weekendsSkipped": 0,
    "holidaysSkipped": 0
  },
  "meta": {
    "endpoint": "business-days",
    "route": "/add",
    "params": {
      "country": "GB",
      "start": "2026-06-10",
      "days": 3,
      "includeStart": true
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

GET /api/business-days/between Count business days in a date range

Live requestRuns against the public API
No key required
GET/api/business-days/between?country=US&from=2026-07-01&to=2026-07-08

Request parameters

ISO 3166-1 alpha-2 country code. Supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA.

Range start (2020–2052).

Range end (2020–2052); must be on or after from.

Include from in the interval when it is a business day.

Include to in the interval when it is a business day.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/business-days/between?country=US&from=2026-07-01&to=2026-07-08"
const res = await fetch("https://randomapi.dev/api/business-days/between?country=US&from=2026-07-01&to=2026-07-08");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/business-days/between?country=US&from=2026-07-01&to=2026-07-08").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/business-days/between?country=US&from=2026-07-01&to=2026-07-08"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 5
country string required

ISO 3166-1 alpha-2 country code. Supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA.

allowed: 2 – 2
example: country=US
from date required

Range start (2020–2052).

example: from=2026-07-01
to date required

Range end (2020–2052); must be on or after from.

example: to=2026-07-08
includeStart boolean

Include from in the interval when it is a business day.

default: true
example: includeStart=false
includeEnd boolean

Include to in the interval when it is a business day.

default: false
example: includeEnd=true
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryName
exclude list

Return all fields except these (comma-separated).

example: exclude=holidaysExcluded
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 10
country string

Canonical country code.

example: US

countryName string

English country name.

example: United States

from string (YYYY-MM-DD)

Range start.

example: 2026-07-01

to string (YYYY-MM-DD)

Range end.

example: 2026-07-08

includeStart boolean

Whether from is included.

example: true

includeEnd boolean

Whether to is included.

example: false

businessDays integer

Business days in the chosen interval.

example: 4

daysExamined integer

Calendar dates inside the chosen boundaries.

example: 7

weekendsExcluded integer

Included-boundary dates excluded as weekends.

example: 2

holidaysExcluded integer

Included-boundary weekday public holidays excluded.

example: 1

Documented examples

Build-generated requests and complete responses 3
US working days across observed July 4
GET /api/business-days/between?country=US&from=2026-07-01&to=2026-07-08 
{
  "data": {
    "country": "US",
    "countryName": "United States",
    "from": "2026-07-01",
    "to": "2026-07-08",
    "includeStart": true,
    "includeEnd": false,
    "businessDays": 4,
    "daysExamined": 7,
    "weekendsExcluded": 2,
    "holidaysExcluded": 1
  },
  "meta": {
    "endpoint": "business-days",
    "route": "/between",
    "params": {
      "country": "US",
      "from": "2026-07-01",
      "to": "2026-07-08",
      "includeStart": true,
      "includeEnd": false
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Closed interval including both dates
GET /api/business-days/between?country=DK&from=2026-12-21&to=2026-12-31&includeEnd=true 
{
  "data": {
    "country": "DK",
    "countryName": "Denmark",
    "from": "2026-12-21",
    "to": "2026-12-31",
    "includeStart": true,
    "includeEnd": true,
    "businessDays": 8,
    "daysExamined": 11,
    "weekendsExcluded": 2,
    "holidaysExcluded": 1
  },
  "meta": {
    "endpoint": "business-days",
    "route": "/between",
    "params": {
      "country": "DK",
      "from": "2026-12-21",
      "to": "2026-12-31",
      "includeStart": true,
      "includeEnd": true
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Exclude the first day
GET /api/business-days/between?country=DE&from=2026-04-01&to=2026-04-08&includeStart=false 
{
  "data": {
    "country": "DE",
    "countryName": "Germany",
    "from": "2026-04-01",
    "to": "2026-04-08",
    "includeStart": false,
    "includeEnd": false,
    "businessDays": 2,
    "daysExamined": 6,
    "weekendsExcluded": 2,
    "holidaysExcluded": 2
  },
  "meta": {
    "endpoint": "business-days",
    "route": "/between",
    "params": {
      "country": "DE",
      "from": "2026-04-01",
      "to": "2026-04-08",
      "includeStart": false,
      "includeEnd": false
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

GET /api/business-days/calendar Inspect an inclusive business-day calendar with exact totals

Returns one row per UTC calendar date. Weekend rows remain weekends even when a public holiday falls there; actual and observed public-holiday labels stay visible in holidays.

Live requestRuns against the public API
No key required
GET/api/business-days/calendar?country=US&from=2021-12-30&to=2022-01-03

Request parameters

ISO 3166-1 alpha-2 country code. Supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA.

First included UTC calendar date (2020–2052).

Last included UTC calendar date; the inclusive range may contain at most 366 dates.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/business-days/calendar?country=US&from=2021-12-30&to=2022-01-03"
const res = await fetch("https://randomapi.dev/api/business-days/calendar?country=US&from=2021-12-30&to=2022-01-03");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/business-days/calendar?country=US&from=2021-12-30&to=2022-01-03").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/business-days/calendar?country=US&from=2021-12-30&to=2022-01-03"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 3
country string required

ISO 3166-1 alpha-2 country code. Supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA.

allowed: 2 – 2
example: country=US
from date required

First included UTC calendar date (2020–2052).

example: from=2021-12-30
to date required

Last included UTC calendar date; the inclusive range may contain at most 366 dates.

example: to=2022-01-03
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryName
exclude list

Return all fields except these (comma-separated).

example: exclude=days
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 9
country string

Canonical country code.

example: US

countryName string

English country name.

example: United States

from string (YYYY-MM-DD)

First included date.

example: 2021-12-30

to string (YYYY-MM-DD)

Last included date.

example: 2022-01-03

totalDays integer

Exact inclusive number of returned dates.

example: 5

businessDays integer

Rows classified business.

example: 2

weekendDays integer

Rows classified weekend, including nominal holidays on weekends.

example: 2

holidayDays integer

Weekday rows excluded by an actual or observed public holiday.

example: 1

days object[]

Inclusive chronological ledger with date, weekday, exclusive classification and public-holiday details.

example: [{"date":"2021-12-31","weekday":"Friday","classification":"holiday","holidays":[{"name":"New Year's Day","localName":"New Year's Day","observed":true,"actualDate":"2022-01-01"}]}]

Documented examples

Build-generated requests and complete responses 3
Cross-year US observed New Year
GET /api/business-days/calendar?country=US&from=2021-12-30&to=2022-01-03 
{
  "data": {
    "country": "US",
    "countryName": "United States",
    "from": "2021-12-30",
    "to": "2022-01-03",
    "totalDays": 5,
    "businessDays": 2,
    "weekendDays": 2,
    "holidayDays": 1,
    "days": [
      {
        "date": "2021-12-30",
        "weekday": "Thursday",
        "classification": "business",
        "holidays": []
      },
      {
        "date": "2021-12-31",
        "weekday": "Friday",
        "classification": "holiday",
        "holidays": [
          {
            "name": "New Year's Day",
            "localName": "New Year's Day",
            "observed": true,
            "actualDate": "2022-01-01"
          }
        ]
      },
      {
        "date": "2022-01-01",
        "weekday": "Saturday",
        "classification": "weekend",
        "holidays": [
          {
            "name": "New Year's Day",
            "localName": "New Year's Day",
            "observed": false,
            "actualDate": "2022-01-01"
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Danish Christmas bank and public days
GET /api/business-days/calendar?country=DK&from=2026-12-23&to=2026-12-31 
{
  "data": {
    "country": "DK",
    "countryName": "Denmark",
    "from": "2026-12-23",
    "to": "2026-12-31",
    "totalDays": 9,
    "businessDays": 6,
    "weekendDays": 2,
    "holidayDays": 1,
    "days": [
      {
        "date": "2026-12-23",
        "weekday": "Wednesday",
        "classification": "business",
        "holidays": []
      },
      {
        "date": "2026-12-24",
        "weekday": "Thursday",
        "classification": "business",
        "holidays": []
      },
      {
        "date": "2026-12-25",
        "weekday": "Friday",
        "classification": "holiday",
        "holidays": [
          {
            "name": "Christmas Day",
            "localName": "Juledag",
            "observed": false,
            "actualDate": "2026-12-25"
          }
        ]
      },
      {
        "date": "2026-12-26",
        "weekday": "Saturday",
        "classification": "weekend",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
British Easter work calendar
GET /api/business-days/calendar?country=GB&from=2026-04-02&to=2026-04-07 
{
  "data": {
    "country": "GB",
    "countryName": "United Kingdom",
    "from": "2026-04-02",
    "to": "2026-04-07",
    "totalDays": 6,
    "businessDays": 2,
    "weekendDays": 2,
    "holidayDays": 2,
    "days": [
      {
        "date": "2026-04-02",
        "weekday": "Thursday",
        "classification": "business",
        "holidays": []
      },
      {
        "date": "2026-04-03",
        "weekday": "Friday",
        "classification": "holiday",
        "holidays": [
          {
            "name": "Good Friday",
            "localName": "Good Friday",
            "observed": false,
            "actualDate": "2026-04-03"
          }
        ]
      },
      {
        "date": "2026-04-04",
        "weekday": "Saturday",
        "classification": "weekend",
        "holidays": []
      },
      {
        "date": "2026-04-05",
        "weekday": "Sunday",
        "classification": "weekend",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Performs business-day arithmetic against the same verified national holiday engine as the Public Holidays API. A business day is a non-rest weekday excluding national holidays whose type is public; observed/substitute weekdays are excluded too. Bank-only days and observances are deliberately not treated as days off. Each country's weekly rest days come from its own ruleset (Saturday + Sunday in every country currently supported) — GET /api/holidays/countries reports them.

Three routes keep the boundary rules explicit:

  • /add moves forward or backward by a signed number of business days. The start date is not counted by default; includeStart=true counts it when it is itself a business day. days=0 always returns the start date.
  • /between counts business days in a range. Its default interval is [from, to) — start included, end excluded — and includeStart / includeEnd let you change either boundary.
  • /calendar returns every date in an inclusive range of at most 366 dates. Each row is classified as business, weekend or holiday, and public-holiday names remain visible on both their actual and observed dates. Weekend dates stay in the weekend total even when they are also the nominal holiday.

The arithmetic responses report how many weekend and holiday dates were skipped, so their results are auditable. Coverage is national-level only (not state, province or municipality holidays), matches the Holidays API's 61-country scope, and is intentionally bounded to 2020–2052; /between spans are capped at 3,660 days and /calendar at 366 returned dates to keep a free Worker request cheap and predictable.

Partial calendars are flagged, not hidden. IN, KE, KR, KZ, MA, NG, PH, SG, TH, TR have holidays on lunar or Hijri calendars that no algorithm can derive; those days are excluded from the holiday engine, so business-day totals for those countries are too high by the number of excluded days in the range. Every response for such a country carries a meta.warnings entry naming exactly what is missing.

Use it for

  • Calculate invoice or SLA due dates without maintaining a holiday table
  • Count working days in delivery, payroll and support-reporting ranges
  • Render an auditable work calendar with actual and observed holiday labels
  • Test scheduling logic around weekends and observed public holidays

Frequently asked questions

Practical answers about this endpoint 5
Which days count as business days?

The country's non-rest weekdays (Monday to Friday everywhere currently supported), excluding national public holidays and their observed substitute days. Bank-only days, observances and regional holidays are outside the calculation.

Which countries can I compute business days for?

The same 61 countries the Public Holidays API covers. GET /api/holidays/countries lists them with their coverage flag; for the ten countries whose calendars are a documented subset, every response warns that the totals may be too high.

Does the start date count?

On /between it does by default, giving a [from, to) interval. On /add it does not; set includeStart=true to count a business-day start as the first day.

Are weekend-observed holidays included?

Yes. Where the national rules define an observed or substitute weekday, that weekday is excluded as a public holiday too.

Can I inspect every date behind the totals?

Yes. /calendar returns an inclusive days[] ledger with one exclusive business/weekend/holiday classification and any actual or observed public-holiday names.

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
Public Holidays API REAL DATA

Real public holidays for 61 countries, computed from official national rules — list a year, check a date, or get the next upcoming holiday.
Date Info API REAL DATA

Real calendar facts for any date — weekday, ISO week, day of year, quarter, leap year, days in month, weekend flag and Unix timestamp. Defaults to today.
Random Date Generator API MOCK DATA

Uniformly random timestamps from any date range — ISO instant, Unix seconds, date, time and weekday — with an exact weekdays-only mode and seeded results.
Current Time API REAL DATA

Current time in any IANA timezone — UTC instant, unix seconds, local date & time, UTC offset, ISO week, day of year and a live DST flag.