Nager.Date Getting Started: Integration Guide (2026)

Getting started overview

Nager.Date provides a Public Holiday API designed for integrating national and regional holiday data into various applications. This guide outlines the essential steps for developers to get started, from account creation and API key retrieval to making a first successful API call. The service is structured to be accessible via standard HTTP requests, with specific endpoints for querying holidays by country and year.

To begin, users typically navigate to the Nager.Date homepage, register for an account, and locate their API key within the user dashboard. This key authenticates requests and manages usage against the chosen tier, including the free tier offering up to 500 requests per day. The API itself is documented via Swagger UI, which provides an interactive interface for exploring available endpoints and parameters.

Quick-reference integration steps

Create an account and get keys

Accessing the Nager.Date Public Holiday API requires registration for an account. This process establishes your user profile and generates the necessary credentials for authenticating API requests. Without a valid API key, requests to the Nager.Date endpoints will not be processed successfully.

Account creation process

1. Navigate to the Nager.Date website: Open your web browser and go to the official Nager.Date homepage.
2. Initiate registration: Look for a "Sign Up" or "Register" link, typically found in the top navigation or a prominent call-to-action button.
3. Provide necessary information: You will typically be asked for an email address, desired password, and potentially other basic contact details. Ensure you use a valid email address as it may be required for verification.
4. Verify email (if prompted): Some services send a verification link to your registered email address to confirm account ownership. Follow the instructions in the email to complete this step.

API key generation and retrieval

Upon successful account creation and login, your API key will be made available through your user dashboard. The API key is a unique string that identifies your application and authorizes your usage of the Nager.Date API.

1. Log in to your account: Use your newly created credentials to log into the Nager.Date portal.
2. Access the dashboard or API settings: Within your account, there should be a section labeled "Dashboard," "API Keys," "Settings," or similar. This is where your API key is displayed and managed.
3. Copy your API Key: The key will be presented as a long alphanumeric string. Copy this key directly. It is crucial to keep this key secure, as it provides access to your account's API usage. Do not hardcode it directly into client-side code that can be easily inspected.
4. Note on API key management: For production applications, consider using environment variables or a secure configuration management system to store API keys rather than embedding them directly in source code. This practice aligns with common security recommendations for API access tokens, as detailed in resources like the OAuth 2.0 Bearer Token Usage specification.

Your first request

After acquiring your API key, you can proceed to make your first request to the Nager.Date Public Holiday API. This example demonstrates how to retrieve public holidays for a specific country and year using a simple HTTP GET request.

API Endpoint structure

The primary endpoint for querying public holidays is typically structured as follows:

GET https://date.nager.at/api/v3/PublicHolidays/{year}/{countryCode}

Where:

• {year}: The four-digit year (e.g., 2026).
• {countryCode}: The two-letter ISO 3166-1 alpha-2 country code (e.g., US for United States, DE for Germany).

Adding your API key

Your API key is typically passed as a query parameter named apiKey. For example:

https://date.nager.at/api/v3/PublicHolidays/2026/US?apiKey=YOUR_API_KEY

Replace YOUR_API_KEY with the actual key copied from your Nager.Date dashboard.

Example using cURL

cURL is a widely available command-line tool for making HTTP requests and is useful for quickly testing API endpoints. To make your first request using cURL:

1. Open your terminal or command prompt.
2. Execute the cURL command: Replace YOUR_API_KEY with your key.

   curl -X GET "https://date.nager.at/api/v3/PublicHolidays/2026/US?apiKey=YOUR_API_KEY"
   

3. Observe the response: A successful response will return a JSON array containing objects, each representing a public holiday. For example, a partial response might look like this:

   [
     {
       "date": "2026-01-01",
       "localName": "New Year's Day",
       "name": "New Year's Day",
       "countryCode": "US",
       "fixed": true,
       "global": true,
       "counties": null,
       "launchYear": null,
       "types": [
         "Public"
       ]
     },
     // ... other holidays
   ]
   

Example using a web browser

For simple GET requests, you can also test the API directly in your web browser:

1. Open your web browser.
2. Paste the constructed URL: Enter the full URL, including your API key, into the browser's address bar (e.g., https://date.nager.at/api/v3/PublicHolidays/2026/US?apiKey=YOUR_API_KEY).
3. Press Enter: The browser will display the raw JSON response directly in the window. Browser extensions for JSON formatting can improve readability.

Example using C# (with the Nager.Date SDK)

Nager.Date offers a dedicated client library for C# developers, simplifying API interaction. This is generally the recommended approach for C# applications.

1. Install the SDK: Add the Nager.Date client library to your C# project using NuGet Package Manager:

   dotnet add package Nager.Date
   

2. Write C# code to make the request:

   using Nager.Date;
   using Nager.Date.Models;
   using System;
   using System.Linq;
   using System.Threading.Tasks;
   
   public class NagerDateExample
   {
       public static async Task Main(string[] args)
       {
           // Replace with your actual API key
           string apiKey = "YOUR_API_KEY"; 
           var dateSystem = new DateSystem(apiKey); 
   
           try
           {
               var publicHolidays = await dateSystem.GetPublicHolidaysAsync(2026, CountryCode.US);
   
               Console.WriteLine($"Public Holidays for US in 2026:");
               foreach (var holiday in publicHolidays.OrderBy(h => h.Date))
               {
                   Console.WriteLine($"- {holiday.Date:yyyy-MM-dd}: {holiday.LocalName}");
               }
           }
           catch (Exception ex)
           {
               Console.WriteLine($"An error occurred: {ex.Message}");
           }
       }
   }
   

3. Run your application: Execute your C# application to see the holiday data printed to the console.

Common next steps

After successfully making your first request, consider these common next steps to further integrate Nager.Date into your application:

• Explore other endpoints: The API offers additional functionalities beyond just getting general public holidays. Review the Nager.Date Swagger UI documentation to discover endpoints such as IsPublicHoliday for checking a specific date, or endpoints for retrieving country information.
• Error handling: Implement robust error handling in your application. The API will return standard HTTP status codes (e.g., 400 Bad Request for invalid parameters, 401 Unauthorized for missing/invalid API key, 429 Too Many Requests for rate limits). Your application should gracefully handle these responses.
• Client library usage: If you are developing in C#, continue to utilize the official Nager.Date .NET client library for streamlined interaction and object mapping. This reduces the amount of boilerplate code required for HTTP requests and JSON parsing.
• Rate limit awareness: Be mindful of the API rate limits associated with your account tier. The free tier, for example, is limited to 500 requests per day. For higher usage, you may need to upgrade to a paid plan.
• Caching strategies: To optimize performance and reduce API calls, consider implementing caching for holiday data that does not change frequently. For example, public holidays for a given year are static and can be stored locally for a period. Developers can refer to general principles of API caching strategies to implement this effectively.
• Integrate into application logic: Begin integrating the retrieved holiday data into your application's core logic, such as scheduling systems, HR applications, or financial systems that need to account for non-working days.

Troubleshooting the first call

If your initial API call encounters issues, review the following common troubleshooting steps:

• Missing or incorrect API key: Double-check that you have included your API key in the request URL and that it is copied correctly from your Nager.Date dashboard. An incorrect key usually results in a 401 Unauthorized or 403 Forbidden HTTP status code.
• Invalid country code or year: Ensure the countryCode parameter uses the two-letter ISO 3166-1 alpha-2 format (e.g., US, DE, GB). Verify the year parameter is a valid four-digit year. Providing malformed parameters may lead to a 400 Bad Request response.
• Network connectivity issues: Confirm your development environment has an active internet connection and is not blocked by a firewall or proxy that prevents outbound HTTP requests to date.nager.at.
• Rate limit exceeded: If you are on the free tier or a paid plan, check your dashboard or the response headers for indications that you have exceeded your daily or hourly request limit. A 429 Too Many Requests status code signals this issue.
• Endpoint path errors: Verify that the base URL and endpoint path are exactly as specified in the Nager.Date API documentation. Typos in the URL can lead to 404 Not Found errors.
• JSON parsing errors: If you are receiving a response but your application cannot parse it, ensure your JSON parser is correctly configured for the response structure. While Nager.Date typically returns valid JSON, unexpected characters or malformed responses (if any) could cause issues.
• CORS issues (for browser-based applications): If developing a client-side web application, ensure that the Nager.Date API supports Cross-Origin Resource Sharing (CORS) for your domain. If CORS is not properly configured, browser security policies may block the request, resulting in network errors in the browser's developer console.