Calculate business days across countries and regions, accounting for weekends, public holidays, and regional variations. Supports general business days, banking days, and government days.
Standards Used
- ISO 8601
- ISO 3166-1
- ISO 3166-2
Additional Information#
Day Types#
| Type | Excludes |
|---|---|
business | Weekends + public holidays |
banking | Weekends + public holidays + bank holidays |
government | Weekends + public holidays + authority holidays |
Regional Precision#
Querying a region (e.g., US-CA) includes both national and regional holidays. California's César Chávez Day (March 31) affects US-CA but not US-TX.
Workweek Handling#
Each location has a standard workweek. Most countries use Monday-Friday. Israel and much of the Middle East use Sunday-Thursday. The workweek field in responses makes this explicit and can be used programmatically.
Conditional Fields#
The check endpoint only includes next_business_day and prev_business_day when the queried date is not a business day.
Endpoints#
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country code (alpha-2) or region code Example: US |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| datequery | string | No | Date to check in YYYY-MM-DD format (defaults to today). Example: 2025-01-15 |
| typequery | any | No | Type of day to check: business, banking, or government. Example: business |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| date | string | Yes | The date that was checked. Example: 2025-01-15 |
| holiday | null | object | No | |
| is_business_day | boolean | Yes | Whether the date is a business day. Example: true |
| location | string | Yes | Location code (country alpha-2 or region code). Example: US |
| next_business_day | string | No | Next business day if the date is not a business day. Example: 2025-01-16 |
| prev_business_day | string | No | Previous business day if the date is not a business day. Example: 2025-01-14 |
| reason | string | No | Reason if not a business day: "weekend" or "holiday". Example: holiday |
| type | string | Yes | The type of day checked. Example: business |
| workweek | string[] | Yes | Days of the week that are working days in this location. Example: ["monday","tuesday","wednesday","thursday","friday"] |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/business-days/US?date=2025-01-15&type=business',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/business-days/US',
params={
'date': '2024-06-21',
'type': 'example'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/business-days/US?date=2025-01-15&type=business"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 402 | Premium subscription required |
| 404 | Location not found |
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country code (alpha-2) or region code Example: US |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| startquery | string | No | Start date in YYYY-MM-DD format (defaults to today). Example: 2025-01-15 |
| daysquery | integer (int32) | Yes | Number of business days to add (must be positive). Example: 5 |
| typequery | any | No | Type of day to count: business, banking, or government. Example: business |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| days | integer (int32) | Yes | Number of business days added. Example: 5 |
| location | string | Yes | Location code (country alpha-2 or region code). Example: US |
| result | string | Yes | The resulting date after adding business days. Example: 2025-01-22 |
| start | string | Yes | The starting date. Example: 2025-01-15 |
| type | string | Yes | The type of day counted. Example: business |
| workweek | string[] | Yes | Days of the week that are working days in this location. Example: ["monday","tuesday","wednesday","thursday","friday"] |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/business-days/US/add?start=2025-01-15&days=5',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/business-days/US/add',
params={
'start': 'example',
'days': '10'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/business-days/US/add?start=2025-01-15&days=5"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 402 | Premium subscription required |
| 404 | Location not found |
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country code (alpha-2) or region code Example: US |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| startquery | string | Yes | Start date (inclusive) in YYYY-MM-DD format. Example: 2025-01-01 |
| endquery | string | Yes | End date (inclusive) in YYYY-MM-DD format. Example: 2025-01-31 |
| typequery | any | No | Type of day to count: business, banking, or government. Example: business |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| business_days | integer (int64) | Yes | Number of business days in the range. Example: 22 |
| end | string | Yes | End date of the range. Example: 2025-01-31 |
| holiday_list | object[] | Yes | List of holidays within the range. |
| holidays | integer (int64) | Yes | Number of holidays that fall on weekdays. Example: 1 |
| location | string | Yes | Location code (country alpha-2 or region code). Example: US |
| start | string | Yes | Start date of the range. Example: 2025-01-01 |
| total_days | integer (int64) | Yes | Total calendar days in the range. Example: 31 |
| type | string | Yes | The type of day counted. Example: business |
| weekend_days | integer (int64) | Yes | Number of weekend days in the range. Example: 8 |
| workweek | string[] | Yes | Days of the week that are working days in this location. Example: ["monday","tuesday","wednesday","thursday","friday"] |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/business-days/US/count?start=2025-01-01&end=2025-01-31',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/business-days/US/count',
params={
'start': 'example',
'end': 'example'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/business-days/US/count?start=2025-01-01&end=2025-01-31"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 402 | Premium subscription required |
| 404 | Location not found |
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country code (alpha-2) or region code Example: US |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| fromquery | string | No | Start date in YYYY-MM-DD format (defaults to today). Example: 2025-01-15 |
| typequery | any | No | Type of day to find: business, banking, or government. Example: business |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| days_until | integer (int64) | Yes | Number of calendar days until the next business day. Example: 1 |
| from | string | Yes | The starting date. Example: 2025-01-15 |
| location | string | Yes | Location code (country alpha-2 or region code). Example: US |
| next | string | Yes | The next business day. Example: 2025-01-16 |
| type | string | Yes | The type of day searched. Example: business |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/business-days/US/next?from=2025-01-15&type=business',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/business-days/US/next',
params={
'from': 'example',
'type': 'example'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/business-days/US/next?from=2025-01-15&type=business"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 402 | Premium subscription required |
| 404 | Location not found |
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| locationpath | string | Yes | Country code (alpha-2) or region code Example: US |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| startquery | string | No | Start date in YYYY-MM-DD format (defaults to today). Example: 2025-01-15 |
| daysquery | integer (int32) | Yes | Number of business days to subtract (must be positive). Example: 5 |
| typequery | any | No | Type of day to count: business, banking, or government. Example: business |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| days | integer (int32) | Yes | Number of business days subtracted. Example: 5 |
| location | string | Yes | Location code (country alpha-2 or region code). Example: US |
| result | string | Yes | The resulting date after subtracting business days. Example: 2025-01-08 |
| start | string | Yes | The starting date. Example: 2025-01-15 |
| type | string | Yes | The type of day counted. Example: business |
| workweek | string[] | Yes | Days of the week that are working days in this location. Example: ["monday","tuesday","wednesday","thursday","friday"] |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/business-days/US/subtract?start=2025-01-15&days=5',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/business-days/US/subtract',
params={
'start': 'example',
'days': '10'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/business-days/US/subtract?start=2025-01-15&days=5"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters |
| 402 | Premium subscription required |
| 404 | Location not found |
| 429 | Rate limit exceeded |