{
  "openapi": "3.1.1",
  "info": {
    "title": "Community - API V3",
    "description": "The Nager.Date Community API is a public service that provides reliable information about public holidays and long weekends for countries around the world. It allows developers to query national holiday dates, check whether a specific day is a public holiday, list upcoming holidays, and explore long-weekend data.\r\n\r\n\r\n\r\nBy using the API, you agree to the <a href=\"https://date.nager.at/Legal/TermsOfService\">Terms of Service.</a>\r\n\r\n**Deprecated**\r\n\r\n> [!caution]\r\n> The V3 API endpoints are deprecated. Support will officially end on January 31, 2027.",
    "termsOfService": "https://date.nager.at/Legal/TermsOfService",
    "contact": {
      "name": "Nager Software Solutions",
      "email": "hello@nager.software"
    },
    "version": "v3"
  },
  "paths": {
    "/api/v3/CountryInfo/{countryCode}": {
      "get": {
        "tags": [
          "Country"
        ],
        "summary": "Retrieves detailed information about a specific country",
        "description": "Provide a valid `ISO 3166-1 alpha-2` country code to retrieve country metadata.\nThe response includes commonly used and official country names, the assigned region, and if available neighboring countries based on geographical borders.",
        "parameters": [
          {
            "name": "countryCode",
            "in": "path",
            "description": "The 2-letter ISO 3166-1 country code (e.g., \"US\", \"GB\").",
            "required": true,
            "schema": {
              "type": "string",
              "default": "us"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the requested country information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CountryInfoWithBordersDto"
                }
              }
            }
          },
          "404": {
            "description": "The provided country code is invalid or not recognized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/AvailableCountries": {
      "get": {
        "tags": [
          "Country"
        ],
        "summary": "Retrieve the complete list of all supported countries",
        "description": "This endpoint returns all countries for which public-holiday data is available.\nEach entry includes the country's name and ISO code.",
        "responses": {
          "200": {
            "description": "Successfully returns the list of supported countries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CountryV3Dto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/LongWeekend/{year}/{countryCode}": {
      "get": {
        "tags": [
          "LongWeekend"
        ],
        "summary": "Retrieve all long weekends for a given country and year",
        "description": "A long weekend is calculated based on public holidays that create an extended break of at least three consecutive days.\nOptional bridge days-weekdays between a holiday and a weekend-can be included to identify potential extended leave opportunities.",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "description": "The target year for which long-weekend data should be calculated.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 2026
            }
          },
          {
            "name": "countryCode",
            "in": "path",
            "description": "A valid `ISO 3166-1 alpha-2` country code determining the region of interest.",
            "required": true,
            "schema": {
              "type": "string",
              "default": "us"
            }
          },
          {
            "name": "availableBridgeDays",
            "in": "query",
            "description": "The maximum number of bridge days to include when determining long-weekend opportunities.",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "subdivisionCode",
            "in": "query",
            "description": "Narrow the calculation to a specific federal state, province, or subdivision (where supported).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully returns the calculated long-weekend results for the specified country and year.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LongWeekendV3Dto"
                  }
                }
              }
            }
          },
          "404": {
            "description": "The provided country code is invalid or not recognized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/PublicHolidays/{year}/{countryCode}": {
      "get": {
        "tags": [
          "PublicHoliday"
        ],
        "summary": "Retrieve the list of all public holidays for the specified year and country",
        "description": "This endpoint returns all officially recognized public holidays for the given country\nand year. Each holiday entry includes the local and English holiday names, information\nabout whether the holiday applies nationally or only in specific subdivisions, and the\nassociated holiday type classifications.",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "description": "The target year for which public holidays should be retrieved.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 2026
            }
          },
          {
            "name": "countryCode",
            "in": "path",
            "description": "A valid `ISO 3166-1 alpha-2` country code.",
            "required": true,
            "schema": {
              "type": "string",
              "default": "us"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the list of public holidays.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicHolidayV3Dto"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request was invalid. See the validation details for more information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "The provided country code is invalid or not recognized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/IsTodayPublicHoliday/{countryCode}": {
      "get": {
        "tags": [
          "PublicHoliday"
        ],
        "summary": "Determines whether today is a public holiday in the specified country, optionally adjusted by a UTC offset",
        "description": "By default, the calculation is based on the current UTC date.\nYou may optionally provide a timezone offset to evaluate the holiday status relative to a different local timezone.\n\nThis endpoint is optimized for simple command-line or automation workflows where only the HTTP status code is required\n\n```\nSTATUSCODE=$(curl --silent --output /dev/stderr --write-out \"%{http_code}\" https://date.nager.at/Api/v3/IsTodayPublicHoliday/AT)\nif [ $STATUSCODE -ne 200 ]; then\n    # handle error\nfi\n```",
        "parameters": [
          {
            "name": "countryCode",
            "in": "path",
            "description": "A valid `ISO 3166-1 alpha-2` country code.",
            "required": true,
            "schema": {
              "type": "string",
              "default": "us"
            }
          },
          {
            "name": "countyCode",
            "in": "query",
            "description": "Optional. The subdivision code (e.g., state, province) to narrow the check.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Optional. UTC timezone offset in hours (range: -12 to +12).",
            "schema": {
              "maximum": 12,
              "minimum": -12,
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Today is a public holiday",
            "content": {
              "application/json": { }
            }
          },
          "204": {
            "description": "Today is not a public holiday",
            "content": {
              "application/json": { }
            }
          },
          "404": {
            "description": "The provided country code is invalid or not recognized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v3/NextPublicHolidays/{countryCode}": {
      "get": {
        "tags": [
          "PublicHoliday"
        ],
        "summary": "Retrieve all upcoming public holidays occurring within the next 365 days for a given country",
        "description": "The list includes only future holidays relative to the current date and is useful for forecasting, event planning, and applications that provide forward-looking holiday insights.",
        "parameters": [
          {
            "name": "countryCode",
            "in": "path",
            "description": "A valid `ISO 3166-1 alpha-2` country code.",
            "required": true,
            "schema": {
              "type": "string",
              "default": "us"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of upcoming public holidays for the next 365 days.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicHolidayV3Dto"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No upcoming holidays were found for the specified country.",
            "content": {
              "application/json": { }
            }
          }
        }
      }
    },
    "/api/v3/NextPublicHolidaysWorldwide": {
      "get": {
        "tags": [
          "PublicHoliday"
        ],
        "summary": "Retrieve all public holidays occurring worldwide within the next 7 days",
        "description": "This global endpoint aggregates upcoming holidays across all supported countries, enabling international systems to detect near-term events.",
        "responses": {
          "200": {
            "description": "A collection of upcoming global public holidays.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicHolidayV3Dto"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No upcoming holidays were found.",
            "content": {
              "application/json": { }
            }
          }
        }
      }
    },
    "/api/v3/Version": {
      "get": {
        "tags": [
          "Version"
        ],
        "summary": "Retrieve the current version information of the Nager.Date library",
        "description": "This endpoint returns detailed version information about the Nager.Date implementation running on the server, including the exact NuGet package version used by the API.",
        "responses": {
          "200": {
            "description": "Successfully retrieved version information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionInfoDto"
                }
              }
            }
          },
          "500": {
            "description": "An unexpected server error occurred.",
            "content": {
              "application/json": { }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CountryInfoDto": {
        "required": [
          "commonName",
          "nativeName",
          "officialName",
          "countryCode",
          "region"
        ],
        "type": "object",
        "properties": {
          "commonName": {
            "type": "string",
            "description": "The commonly used name of the country."
          },
          "nativeName": {
            "type": "string",
            "description": "The name of the country in its native language."
          },
          "officialName": {
            "type": "string",
            "description": "The official name of the country."
          },
          "countryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code."
          },
          "region": {
            "type": "string",
            "description": "Geopolitical or continental region of the country."
          }
        },
        "description": "Detailed information about a country."
      },
      "CountryInfoWithBordersDto": {
        "required": [
          "commonName",
          "nativeName",
          "officialName",
          "countryCode",
          "region"
        ],
        "type": "object",
        "properties": {
          "commonName": {
            "type": "string",
            "description": "The commonly used name of the country."
          },
          "nativeName": {
            "type": "string",
            "description": "The name of the country in its native language."
          },
          "officialName": {
            "type": "string",
            "description": "The official name of the country."
          },
          "countryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code."
          },
          "region": {
            "type": "string",
            "description": "Geopolitical or continental region of the country."
          },
          "borders": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/CountryInfoDto"
            },
            "description": "Neighboring countries based on geographical borders."
          }
        },
        "description": "Detailed information about a country, including neighboring countries."
      },
      "CountryV3Dto": {
        "required": [
          "countryCode",
          "name"
        ],
        "type": "object",
        "properties": {
          "countryCode": {
            "type": "string",
            "description": "The ISO 3166-1 alpha-2 country code (e.g., \"US\", \"DE\")."
          },
          "name": {
            "type": "string",
            "description": "The common name of the country."
          }
        },
        "description": "Represents a country supported by the Nager.Date API."
      },
      "HolidayTypes": {
        "enum": [
          "Public",
          "Bank",
          "School",
          "Authorities",
          "Optional",
          "Observance"
        ],
        "type": "string",
        "format": "string"
      },
      "LongWeekendV3Dto": {
        "type": "object",
        "properties": {
          "startDate": {
            "type": "string",
            "description": "The start date of the long weekend.",
            "format": "date"
          },
          "endDate": {
            "type": "string",
            "description": "The end date of the long weekend.",
            "format": "date"
          },
          "dayCount": {
            "type": "integer",
            "description": "Total number of days in the long weekend.",
            "format": "int32"
          },
          "needBridgeDay": {
            "type": "boolean",
            "description": "Indicates whether a bridge day is required to achieve the long weekend."
          },
          "bridgeDays": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            },
            "description": "Optional bridge days that extend the weekend."
          }
        },
        "description": "Represents a long weekend, including optional bridge days."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "null",
              "string"
            ]
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "status": {
            "type": [
              "null",
              "integer"
            ],
            "format": "int32"
          },
          "detail": {
            "type": [
              "null",
              "string"
            ]
          },
          "instance": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "PublicHolidayV3Dto": {
        "required": [
          "date",
          "localName",
          "name",
          "countryCode",
          "types"
        ],
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "The date of the holiday.",
            "format": "date"
          },
          "localName": {
            "type": "string",
            "description": "Local name of the holiday."
          },
          "name": {
            "type": "string",
            "description": "English name of the holiday."
          },
          "countryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code."
          },
          "fixed": {
            "type": "boolean",
            "description": "Indicates if this holiday occurs on the same date every year."
          },
          "global": {
            "type": "boolean",
            "description": "Indicates if this holiday applies to the entire country."
          },
          "counties": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            },
            "description": "ISO-3166-2 codes of the subdivisions where this holiday applies"
          },
          "launchYear": {
            "type": [
              "null",
              "integer"
            ],
            "description": "The year the holiday was first observed.",
            "format": "int32"
          },
          "types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HolidayTypes"
            },
            "description": "List of holiday types this holiday is classified under."
          }
        },
        "description": "Represents a public holiday."
      },
      "VersionInfoDto": {
        "required": [
          "name",
          "version"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the library."
          },
          "version": {
            "type": "string",
            "description": "The version of the library."
          }
        },
        "description": "Version information."
      }
    }
  },
  "tags": [
    {
      "name": "Country",
      "description": "Provides access to detailed country information and the list of all countries supported by the API. This includes general metadata such as country names, codes, regions, and related details."
    },
    {
      "name": "LongWeekend",
      "description": "Covers operations for retrieving long-weekend information. These endpoints help identify extended weekends created by public holidays, including optional bridge days."
    },
    {
      "name": "PublicHoliday",
      "description": "Includes functionality for retrieving public-holiday data, checking whether a specific day is a public holiday, and listing upcoming holidays."
    },
    {
      "name": "Version",
      "description": "Returns information about the current version of the Nager.Date API in use."
    }
  ]
}