Non-Working Days Getting Started: API Access & First Call (2026)

Getting started overview

Getting started with the Non-Working Days API involves a sequence of steps designed to enable quick integration of global holiday data into various applications. This process typically includes account creation, obtaining an API key for authentication, and executing an initial API call to retrieve holiday information. The API is a RESTful web service, meaning it uses standard HTTP methods (like GET) to access resources, and responses are commonly formatted in JSON, a widely adopted data interchange format (JSON specification).

The Non-Working Days API provides comprehensive data for public holidays across more than 250 countries and regions, making it suitable for applications requiring accurate scheduling, payroll processing, or any business logic dependent on non-working days. The API's design emphasizes ease of use, with clear documentation and examples in multiple programming languages, including cURL, Python, JavaScript, PHP, and Ruby.

Before making your first API call, ensure you have an active internet connection and a development environment configured to send HTTP requests and parse JSON responses. Many programming languages offer built-in libraries or widely-used third-party packages for this purpose. For instance, Python has the requests library, JavaScript environments often use fetch or axios, and PHP can use cURL or Guzzle.

Here's a quick reference table outlining the essential steps to get up and running:

Create an account and get keys

To access the Non-Working Days API, you must first create an account and obtain an API key. This key serves as your primary authentication credential for all API requests.

Account Registration

1. Navigate to the Non-Working Days homepage.
2. Look for a "Sign Up" or "Get API Key" button, typically located in the top right corner or prominently displayed on the page.
3. Complete the registration form by providing your email address and creating a password. You may also be asked for basic company or usage information.
4. Verify your email address if prompted. An email containing a verification link will be sent to the address you provided. Click this link to activate your account.

Non-Working Days offers a free tier that includes 1,000 requests per month, which is sufficient for initial testing and development. For higher request volumes, various paid plans are available, starting at $19/month for 50,000 requests/month.

Retrieving Your API Key

After successfully registering and logging into your Non-Working Days account, your API key will be accessible from your personal dashboard:

1. Log in to your Non-Working Days account.
2. On your dashboard, locate a section labeled "API Key," "Credentials," or similar. This is where your unique API key will be displayed.
3. Copy your API key. It's a long string of alphanumeric characters. Treat this key as sensitive information, similar to a password, to prevent unauthorized access to your account and API usage.

The API key is essential for authenticating your requests. Without it, the API will reject your calls, typically returning an authentication error. The Non-Working Days API documentation provides specific guidance on how to include this key in your requests, usually as a query parameter or an HTTP header, as detailed in the "Your first request" section.

Your first request

Once you have your API key, you can make your first request to the Non-Working Days API. The primary endpoint for retrieving holiday data is straightforward. This example demonstrates how to fetch holidays for a specific country and year.

API Endpoint

The base URL for the Non-Working Days API is https://api.nonworkingdays.com/v1/holidays.

Required Parameters

• api_key: Your unique API key.
• country: The two-letter ISO 3166-1 alpha-2 country code (e.g., US for United States, GB for Great Britain).
• year: The year for which you want to retrieve holidays (e.g., 2026).

Example Request (cURL)

cURL is a command-line tool and library for transferring data with URLs, commonly used for testing API endpoints. Replace YOUR_API_KEY with your actual key.

curl "https://api.nonworkingdays.com/v1/holidays?api_key=YOUR_API_KEY&country=US&year=2026"

Example Request (Python)

This Python example uses the requests library to make an HTTP GET request. Install it first: pip install requests.

import requests
import json

api_key = "YOUR_API_KEY"
country_code = "US"
year = 2026

url = f"https://api.nonworkingdays.com/v1/holidays?api_key={api_key}&country={country_code}&year={year}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
except requests.exceptions.ConnectionError as err:
    print(f"Connection error occurred: {err}")
except requests.exceptions.Timeout as err:
    print(f"Timeout error occurred: {err}")
except requests.exceptions.RequestException as err:
    print(f"An error occurred: {err}")

Example Request (JavaScript - Node.js with fetch)

This JavaScript example uses the built-in fetch API in Node.js (available in recent versions) or browsers. For older Node.js versions, you might need a library like node-fetch.

const fetch = require('node-fetch'); // Remove this line if using native fetch in Node.js v18+

const apiKey = "YOUR_API_KEY";
const countryCode = "US";
const year = 2026;

async function getHolidays() {
  const url = `https://api.nonworkingdays.com/v1/holidays?api_key=${apiKey}&country=${countryCode}&year=${year}`;
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log(JSON.stringify(data, null, 2));
  } catch (error) {
    console.error("Error fetching holidays:", error);
  }
}

getHolidays();

Expected Response Structure

A successful response will typically return a JSON object containing an array of holiday objects. Each holiday object will include details such as the holiday's name, date, and type.

{
  "status": "success",
  "country": "US",
  "year": 2026,
  "holidays": [
    {
      "name": "New Year's Day",
      "date": "2026-01-01",
      "type": "public_holiday"
    },
    {
      "name": "Martin Luther King, Jr.'s Birthday",
      "date": "2026-01-19",
      "type": "public_holiday"
    },
    // ... more holidays
  ]
}

Verifying this structure confirms that your API key is valid and your request was correctly formatted.

Common next steps

After successfully making your first API call, consider these common next steps to further integrate Non-Working Days into your applications:

1. Explore Additional Endpoints and Parameters: The Non-Working Days API offers various parameters to refine your holiday searches, such as filtering by specific regions within a country or retrieving a list of supported countries. Review the API reference documentation to understand all available options and endpoints.
2. Implement Error Handling: Robust applications anticipate and gracefully handle API errors. This includes network issues, invalid API keys, rate limit exceeded responses, or malformed requests. Implement try-catch blocks or similar error-handling mechanisms in your chosen programming language.
3. Manage API Keys Securely: Never hardcode your API key directly into client-side code or publicly accessible repositories. For server-side applications, use environment variables to store and access your API key. For client-side applications, consider using a backend proxy to make API calls, thereby keeping your key secure on the server. Options such as Google Cloud Secret Manager or AWS Secrets Manager provide secure storage for API keys.
4. Monitor Usage and Stay Within Limits: Keep track of your API usage to ensure you stay within your plan's request limits. The Non-Working Days dashboard typically provides usage statistics. Implement logging or monitoring in your application to track calls made to the API.
5. Caching Strategies: For frequently requested, static data like historical holidays, consider implementing caching to reduce API calls and improve application performance. Store retrieved data locally for a defined period and refresh it periodically.
6. Integrate into Your Application Logic: Begin integrating the retrieved holiday data into your core application features, such as scheduling, calendar displays, or business process automation.
7. Explore Other Supported Languages: If you're using a language other than cURL, Python, or JavaScript, check the Non-Working Days API documentation for examples in PHP, Ruby, or other languages.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems you might face:

Common Error Codes and Their Solutions

• 401 Unauthorized / Invalid API Key:
  • Issue: Your API key is incorrect, missing, or expired.
  • Solution: Double-check that you have copied the API key exactly as it appears in your Non-Working Days dashboard. Ensure it's included correctly in your request, typically as a api_key query parameter. Regenerate the key from your dashboard if you suspect it's compromised or invalid.
• 400 Bad Request / Missing or Invalid Parameters:
  • Issue: One or more required parameters (e.g., country, year) are missing or incorrectly formatted.
  • Solution: Verify that all required parameters are present in your request URL and their values conform to the expected format (e.g., a two-letter ISO country code for country, a four-digit year for year). Consult the API documentation for specific parameter requirements.
• 404 Not Found:
  • Issue: The requested endpoint does not exist, or the base URL is incorrect.
  • Solution: Confirm that your base URL is https://api.nonworkingdays.com/v1/holidays and that there are no typos.
• 429 Too Many Requests / Rate Limit Exceeded:
  • Issue: You have exceeded the number of requests allowed within a specific time frame by your plan.
  • Solution: Wait for the rate limit to reset (often indicated in response headers like Retry-After). For production applications, implement rate limiting strategies, such as exponential backoff, and consider upgrading your Non-Working Days plan if persistent.
• 5xx Server Error:
  • Issue: An internal server error occurred on the Non-Working Days side.
  • Solution: These errors are typically not due to your request. Wait a few moments and retry the request. If the issue persists, check the Non-Working Days status page (if available) or contact their support.

General Debugging Tips

• Check Network Connectivity: Ensure your development environment has an active internet connection and no firewalls are blocking outgoing requests to api.nonworkingdays.com.
• Inspect Full Response: Always print or log the full HTTP response, including status codes and response bodies, as they often contain detailed error messages that can guide your debugging.
• Use a REST Client: Tools like Postman or Insomnia allow you to construct and send API requests manually, helping isolate issues related to your code versus the API itself.
• Refer to Documentation: The Non-Working Days API documentation is the authoritative source for valid endpoints, parameters, and expected responses.
• Consult Official Examples: Compare your code against the official code examples provided in the documentation for your chosen programming language.