NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Working Days API

The Working Days API provides information about working days and non-working days (weekends and public holidays) for countries around the world.

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
(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
305ms326ms400ms593ms1123ms

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

/v1/workingdays GET

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

Returns a list of working days and non-working days for a given country and year/month.

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

Parameters

  • country  required

    2-letter ISO country code.

  • year  optional premium only

    Calendar year between 1980 and 2050 (inclusive). By default, the current year is used.

  • month  optional

    Month number (1-12). If provided, returns data for just that month.

  • weekend  optional

    Comma-separated list of weekend days (mon, tue, wed, thu, fri, sat, sun). This parameter is optional: if not provided, the default weekend days will be determined based on the country. If specified, your values will override the country defaults.

  • public_holidays  optional

    Whether to include public holidays as non-working days (true/false). Defaults to true.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

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.

Sample Request Live Demo!

country
year premium
month
weekend
public_holidays

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

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

Headers

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

Sample Response

JSON
{
    num_working_days:251,
    num_non_working_days:114,
    working_days:[
      "2025-01-02",
      "2025-01-03",
      "2025-01-06",
      "2025-01-07",
      "..."
    ],
    non_working_days:[
      {
        date:"2025-01-01",
        reasons:[
          "public holiday",
          "..."
        ],
        holiday_name:"New Year's Day"
      },
      {
        date:"2025-01-04",
        reasons:[
          "weekend",
          "..."
        ]
      },
      "..."
    ]
}

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/workingdays?country=US&year=2025" \ -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.

/v1/isworkingday GET

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

Returns whether a given date is a working day for a given country.

Parameters

  • country  required

    2-letter ISO country code.

  • date  required

    Date in YYYY-MM-DD format. Must be between 1980-01-01 and 2050-12-31 (inclusive).

  • weekend  optional

    Comma-separated list of weekend days (mon,tue,wed,thu,fri,sat,sun). This parameter is optional: if not provided, the default weekend days will be determined based on the country. If specified, your values will override the country defaults.

  • public_holidays  optional

    Whether to include public holidays as non-working days (true/false). Defaults to true.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful.

  • date

    The queried date.

  • country

    2-letter ISO country code.

  • day_of_week

    Day of the week (Monday through Sunday).

  • is_workday

    Whether the date is a working day.

  • non_working_reason

    List of reasons why the date is not a working day (if applicable).

  • public_holiday_name

    Name of the public holiday (if applicable).

Sample Request Live Demo!

country
date
weekend
public_holidays

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/isworkingday?country=US&date=2025-01-01

Headers

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

Sample Response

JSON
{
    date:"2025-01-01",
    country:"US",
    day_of_week:"Wednesday",
    is_workday:false,
    non_working_reason:[
      "public holiday"
    ],
    public_holiday_name:"New Year's Day"
}

Frequently Asked Questions

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • Pass a 2-letter ISO country code (required), optionally with year (1980-2050, defaults to the current year and requires a premium plan) and month (1-12) to scope results to a single month. Omitting month returns data for the entire year.
  • Yes. Both endpoints accept an optional weekend parameter, a comma-separated list of days (mon, tue, wed, thu, fri, sat, sun) that overrides the country defaults, and a public_holidays flag (defaults to true) to control whether public holidays are treated as non-working days.
  • 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.