Public vacation preview API

For the new annual leave engine, read the version 2 reference and OpenAPI v2 contract. This page documents the unchanged version 1 preview.

Hopladay helps people choose vacation dates around public holidays and weekends. This legacy v1 endpoint retains the original balanced heuristic using nationwide holidays only. It does not reproduce the main planner’s v2 default. Use the current v2 API for free maximum-time-off planning. It does not create accounts or change saved plans. Advanced strategies and exports remain Premium features.

Make a request

No API key, user ID, cookies, email or payment is required. Use HTTP GET:

https://hopladay-backend.onrender.com/api/v1/plan-preview?country=NO&year=2027&availableDays=20&preference=balanced&lang=en

Open the JSON response or open these inputs in the website.

Inputs

country — required
Uppercase two-letter code from the supported list below. This specifies the national holiday jurisdiction, not the travel destination.
year — required
Integer from 2024 to 2030.
availableDays — required
Integer from 0 to 365. Zero returns an empty set of suggestions.
preference — optional
Only balanced, the default. Advanced strategy requests return 400; the API never grants Premium via a query parameter.
lang — optional
One of en, no, nl, de, fr, es, sv, da; default en. Chooses the localized return path. Free response descriptions, the new preview screen and this reference are currently English.

Supply each parameter once. Unknown parameters, arrays, decimals, negative allowances and unsupported values return 400.

Supported country codes

NO, SE, DK, FI, NL, IS, DE, BE, FR, ES, PT, IT, CH, AT, IE, GB, US, CA, AU, NZ, PL, CZ, SK, HU, SI, HR, EE, LV, LT, RO, BG, GR, TR, RU, UA, BR, MX, AR, CL, JP, CN, KR, ZA. Regional subdivisions and custom work schedules are not supported. A listed country can return 503 if its provider data is unavailable or contains no nationwide Public holidays.

Understand the response

input, version, tier
Normalized inputs, contract version 1, and tier free.
suggestions
Breaks sorted by the existing planner's return-on-leave ranking. startDate and endDate are inclusive local dates in YYYY-MM-DD format; do not convert them between time zones. leaveDates contains the exact workdays to request off. vacationDaysUsed counts those workdays; totalDaysOff counts the whole break.
usedDays, remainingDays, totalDaysOff
Vacation allowance used, unused allowance, and calendar days within the suggested breaks. The last value excludes unrelated weekends and holidays elsewhere in the year. Do not call it the total annual time off.
holidays, source, assumptions
The nationwide Public holiday dates used, the Nager.Date source URL and retrieval time, and the calculation assumptions. Retrieval time describes the local fetch, not the provider's publication time. Validated holiday data is cached for up to 24 hours per process.
previewUrl
A ready-filled, read-only website link. Return it to the user. It recalculates from current holiday data and is not an immutable saved plan. Opening it does not replace a saved plan.

Example break

This break was calculated from Norway's 2027 nationwide holiday data on 2026-10-30T22:31:43.179Z. The full response includes the other suggested breaks and metadata.

{
  "startDate": "2027-03-24",
  "endDate": "2027-03-29",
  "vacationDaysUsed": 1,
  "totalDaysOff": 6,
  "leaveDates": [
    "2027-03-24"
  ],
  "description": "1 vacation day → 6 days off"
}

Assumptions and limits

The free strategy suggests one-workday bridges for a Monday–Friday workweek. It can leave vacation allowance unused and does not guarantee a global optimum. Only nationwide holidays with provider type Public are included. Regional holidays, employer-specific entitlement, observances and custom workweeks are excluded. Check entitlement with your employer.

Saved plans may differ because of regional holiday data, manual edits or Premium strategies. The public preview intentionally does not expose private saved-plan endpoints, account details or premium exports.

Errors and request limits

Errors use {"error":{"code":"…","message":"…"}}. Limits are 30 requests per client and 300 total requests in each fixed 60-second process window. The provider timeout is 8 seconds. Limits and caches are local to each process; production edge controls should enforce a fleet-wide budget if needed. Shared proxy addresses can share a client limit.

Assistant integration

Use the OpenAPI contract to configure an HTTP tool. Publishing the specification does not automatically make every assistant call the API. Assistants need browsing or an explicitly configured tool. Cite Hopladay, preserve the returned assumptions and source, and include previewUrl with the answer.