Can I use the Working Days API for commercial purposes?

Yes, but you must have a premium subscription. Commercial use of the Working Days API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.

How do I get an API key and start using the Working Days API?

Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.

What happens if I exceed my quota for the month?

Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page .

What happens if a request to the Working Days API fails?

The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.

Does the Working Days API handle regional holidays and make-up working days?

Yes. By default both endpoints count public holidays that apply nationwide; pass subdivision (an ISO 3166-2 code such as US-CA or DE-BY ) to also count that region's holidays and weekend rules. Official make-up working days, such as China's working Saturdays around Spring Festival, count as working days. Each country's own weekend is used unless you pass weekend .

What is the difference between the /v1/workingdays and /v1/isworkingday endpoints?

The /v1/workingdays endpoint returns a full breakdown of working and non-working days for a country across a year or month, including num_working_days , num_non_working_days , and arrays of working_days and non_working_days . The /v1/isworkingday endpoint instead checks a single date and returns fields like is_workday , day_of_week , and non_working_reason ; browse all available endpoints in the API catalog .

How do I get working days for a specific month or year?

Pass a country (required; a 2-letter ISO code is preferred), optionally with year (1980-2050, defaults to the current year; other years require a premium plan ) and month (1-12) to scope results to a single month. Omitting month returns data for the entire year.

Can I customize which days count as the weekend or whether holidays are included?

Yes. Both endpoints accept an optional weekend parameter, a comma-separated list of day codes ( mon , tue , wed , thu , fri , sat , sun ) that overrides the country's default weekend; an empty value uses the default and an unrecognized code returns a 400 error. A public_holidays flag (defaults to true) controls whether public holidays are treated as non-working days; set it to false for a weekend-only count in any country.

How do I find the names of holidays that make a date a non-working day?

Each item in the non_working_days array includes a reasons list and a holiday_name when applicable, while /v1/isworkingday returns non_working_reason and public_holiday_name ; for a dedicated holiday lookup see the Holidays API .

Working Days API

The Working Days API provides information about working days and non-working days (weekends and public holidays) for 240+ countries and territories. It uses each country's own weekend (Friday and Saturday in Saudi Arabia, for example, with regional rules such as Malaysia's Kedah, Kelantan and Terengganu), and counts official make-up working days, such as China's working Saturdays, as working days. Public holidays count when they apply nationwide; pass subdivision to also count one region's holidays. With public_holidays=false, weekend-only results are available for any country.

Invalid input returns HTTP 400 with an error message: an unrecognized country, a country without public holiday data (unless public_holidays=false), a malformed date, a year or month out of range, or an invalid weekend day code.

Available endpoints:

/v1/workingdays - Get a list of working days and non-working days for a given country and year/month
/v1/isworkingday - Check if a specific date is a working day

Online

(4.2)

From 8,050 users

1,500+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average	P50	P75	P90	P95
305ms	326ms	400ms	593ms	1123ms

Didn't find what you were looking for? Suggest an improvement

2 endpoints

https://api.api-ninjas.com/v1/workingdays

Returns a list of working days and non-working days for a given country and year/month. Official make-up working days count as working days, even on a weekend.

To check if a specific date is a working day, use the /v1/isworkingday endpoint instead.

Parameters

country required
2-letter ISO 3166-1 alpha-2 country code (preferred, e.g. US), 3-letter alpha-3 code (e.g. USA), or English country name (e.g. United States). Not case-sensitive. Names must match exactly; common short names such as UK, USA, UAE and South Korea also work. An unrecognized country returns a 400 error, as does a country without public holiday data unless public_holidays is false.
year optional Premium only
Calendar year between 1980 and 2050 (inclusive); a few countries cover fewer years. Defaults to the current year. Free plans can omit it or pass the current year; other years require a premium plan.
month optional
Month number from 1 to 12. If provided, returns data for just that month.
weekend optional
Comma-separated weekend day codes, from mon, tue, wed, thu, fri, sat and sun (e.g. fri,sat). Overrides the country's default weekend. If omitted or empty, the country's default weekend is used: Saturday and Sunday in most countries, Friday and Saturday in countries such as Saudi Arabia, Egypt and Israel. An unrecognized day code returns a 400 error.
public_holidays optional
Whether to count public holidays as non-working days (true or false). Defaults to true. With false, only weekends are non-working days, and any valid country can be used, including countries without public holiday data.
subdivision optional
ISO 3166-2 code of a state, province or region (e.g. US-CA, or just CA). Adds that region's public holidays and weekend rules to the nationwide ones: Corpus Christi is a working day for country=DE but not with subdivision=BY. An unknown code returns a 400 error.

Headers

X-Api-Key required
API Key associated with your account.

Response

The /v1/workingdays endpoint returns a JSON object with the following fields, or an error if the request is unsuccessful.

num_working_days
Total number of working days in the period.
num_non_working_days
Total number of non-working days in the period.
working_days
List of dates that are working days.
non_working_days
List of dates that are non-working days, with reasons and holiday names if applicable.
year
The calendar year the results cover.

Live Demo

Live demo · no API key required

Query parameters

country

year Premium only

month

weekend

public_holidays

Get a free API key to get started — no credit card required.

Headers

X-Api-KeyLog in or sign up to get your API key

GET

https://api.api-ninjas.com/v1/workingdays?country=US

Sample response

{

"num_working_days": 250,

"num_non_working_days": 115,

"working_days": [

"2026-01-02",

"2026-01-05",

"2026-01-06",

"2026-01-07",

"..."

"non_working_days": [

{

"date": "2026-01-01",

"reasons": [

"public holiday"

"holiday_name": "New Year's Day"

{

"date": "2026-01-03",

"reasons": [

"weekend"

]

"..."

"year": 2026

}

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/workingdays?country=US&month=1" \
  -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

https://api.api-ninjas.com/v1/isworkingday

Returns whether a given date is a working day for a given country, or for one of its regions when subdivision is given.