{"openapi":"3.1.0","info":{"title":"Dagsmart API","version":"3.0.0","description":"Reliable data on the Swedish calendar: public holidays, de facto holidays, bridge days and half days."},"servers":[{"url":"https://api.dagsmart.se"}],"components":{"schemas":{"HolidaysResponse":{"type":"object","properties":{"year":{"type":"integer","example":2026},"count":{"type":"integer","description":"Number of entries in the list below.","example":13},"days":{"type":"array","items":{"$ref":"#/components/schemas/Day"}}},"required":["year","count","days"]},"Day":{"type":"object","properties":{"date":{"type":"string","example":"2026-06-06"},"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday, 7 is Sunday.","example":6},"holidayType":{"type":["string","null"],"enum":["public","defacto",null],"description":"What the day is, regardless of how you asked: the strongest observance decides, and Sundays are public holidays in their own right, Saturdays de facto ones. Null on an ordinary working day. The sundays and saturdays flags only decide which days are listed, never what a day is."},"workingDay":{"type":"boolean","description":"Neither a weekend nor a holiday. True exactly when holidayType is null.","example":false},"observances":{"type":"array","items":{"$ref":"#/components/schemas/Observance"},"description":"Always a list, and never contains Saturday or Sunday – those are properties of the date, not feasts. Two holidays can share a date: 1 May 2008 was both Ascension Day and May Day."}},"required":["date","weekday","holidayType","workingDay","observances"]},"Observance":{"type":"object","properties":{"code":{"type":"string","description":"Stable identifier for the observance. Names may be reworded; codes may not.","example":"nationalDay"},"holidayType":{"type":"string","enum":["public","defacto"],"description":"A public holiday is one under the Swedish Public Holidays Act (1989:253). A de facto holiday is not, but is treated as one in practice. Note that de facto does not mean unrecognised in law: Midsummer Eve, Christmas Eve and New Year's Eve are equated with Sunday by the Annual Leave Act (1977:480) s. 3 a and by the Act on the Calculation of Statutory Time (1930:173) s. 2. Easter Eve and Whitsun Eve rest on custom, and always fall on a Saturday."},"name":{"$ref":"#/components/schemas/Names"},"feast":{"$ref":"#/components/schemas/Feast"}},"required":["code","holidayType","name","feast"]},"Names":{"type":"object","properties":{"sv":{"type":"string","example":"nationaldagen"},"en":{"type":"string","example":"National Day of Sweden"}},"required":["sv","en"]},"Feast":{"type":"object","properties":{"code":{"type":"string","description":"Stable identifier for the feast. Names may be reworded; codes may not.","example":"christmas"},"name":{"allOf":[{"$ref":"#/components/schemas/Names"},{"example":{"sv":"jul","en":"Christmas"}}]}},"required":["code","name"],"description":"The feast the observance belongs to."},"Problem":{"type":"object","properties":{"type":{"type":"string","example":"https://dagsmart.se/api/problems/invalid-year"},"title":{"type":"string","example":"Invalid year"},"status":{"type":"integer","example":400},"detail":{"type":"string"}},"required":["type","title","status"]},"BridgeDaysResponse":{"type":"object","properties":{"year":{"type":"integer","example":2026},"count":{"type":"integer","description":"Number of entries in the list below.","example":13},"days":{"type":"array","items":{"$ref":"#/components/schemas/Day"}}},"required":["year","count","days"]},"HalfDaysResponse":{"type":"object","properties":{"year":{"type":"integer","example":2026},"count":{"type":"integer","description":"Number of entries in the list below.","example":13},"days":{"type":"array","items":{"$ref":"#/components/schemas/Day"}}},"required":["year","count","days"]},"Period":{"type":"object","properties":{"from":{"type":"string","description":"Echoed as sent.","example":"2026-03-01"},"to":{"type":"string","description":"Echoed as sent.","example":"2026-03-31"},"bounds":{"type":"string","enum":["inclusive","exclusive","from","to"],"description":"The reading applied, whether you asked for it or got the default.","example":"inclusive"},"counted":{"type":["object","null"],"properties":{"first":{"type":"string","example":"2026-03-01"},"last":{"type":"string","example":"2026-03-31"}},"required":["first","last"],"description":"The days actually counted, after bounds. Null when the endpoints cancel out — two identical dates with bounds=exclusive contain no days."},"calendarDays":{"type":"integer","description":"Days in the period, counted according to bounds.","example":31},"duration":{"$ref":"#/components/schemas/Duration"},"workingDays":{"type":"integer","description":"Days that are neither weekends nor holidays.","example":22},"daysOff":{"$ref":"#/components/schemas/DaysOff"},"bridgeDays":{"type":"integer","description":"Working days wedged between a holiday and a weekend.","example":0},"halfDays":{"type":"integer","description":"Days customarily worked as half days.","example":0}},"required":["from","to","bounds","counted","calendarDays","duration","workingDays","daysOff","bridgeDays","halfDays"]},"Duration":{"type":"object","properties":{"years":{"type":"integer","example":0},"months":{"type":"integer","example":1},"days":{"type":"integer","example":0}},"required":["years","months","days"],"description":"The period as calendar units, the way a statutory deadline is counted: one month from 1 January is 1 February, whatever February happens to be worth in days."},"DaysOff":{"type":"object","properties":{"total":{"type":"integer","description":"Days that are neither working days: total + workingDays = calendarDays.","example":9},"publicHolidays":{"type":"integer","description":"Of the days off: public holidays under the Act (1989:253). Sundays are counted here, being public holidays in their own right.","example":5},"defactoHolidays":{"type":"integer","description":"Of the days off: days equated with holidays in practice. Saturdays are counted here, being days off without being holidays in law.","example":4},"namedDays":{"type":"integer","description":"Of the days off: days carrying at least one named observance.","example":0},"weekendDays":{"type":"integer","description":"Of the days off: days off solely because of the weekday.","example":9}},"required":["total","publicHolidays","defactoHolidays","namedDays","weekendDays"],"description":"Two independent splits of the same total: by law (public + defacto) and by what the day is (named + weekend). Each pair sums to total."},"Shift":{"type":"object","properties":{"date":{"type":"string","description":"Echoed as sent.","example":"2026-01-30"},"postpone":{"type":"boolean","description":"Whether the Sunday rule was asked for.","example":true},"steps":{"type":"array","items":{"$ref":"#/components/schemas/AppliedStep"},"description":"The chain in the order it was applied, each step with its own result. Order changes the answer: +1 month then +30 days is not +30 days then +1 month."},"landed":{"allOf":[{"$ref":"#/components/schemas/Day"},{"description":"Where the steps landed, before the Sunday rule had its say."}]},"postponed":{"type":"boolean","description":"True when the Sunday rule actually moved the date.","example":false},"result":{"allOf":[{"$ref":"#/components/schemas/Day"},{"description":"The answer."}]},"period":{"$ref":"#/components/schemas/PeriodSummary"}},"required":["date","postpone","steps","landed","postponed","result","period"]},"AppliedStep":{"type":"object","properties":{"unit":{"type":"string","enum":["d","b","w","m","y"],"example":"m"},"amount":{"type":"integer","example":1},"constrained":{"type":"boolean","description":"True when month arithmetic had to constrain the day: 31 January plus one month is 28 February, because 31 February does not exist.","example":true},"result":{"allOf":[{"$ref":"#/components/schemas/Day"},{"description":"Where the chain stood after this step."}]}},"required":["unit","amount","constrained","result"]},"PeriodSummary":{"type":["object","null"],"properties":{"from":{"type":"string","example":"2026-01-30"},"to":{"type":"string","example":"2026-02-26"},"calendarDays":{"type":"integer","description":"Days in the period, counted according to bounds.","example":31},"duration":{"$ref":"#/components/schemas/Duration"},"workingDays":{"type":"integer","description":"Days that are neither weekends nor holidays.","example":22},"daysOff":{"$ref":"#/components/schemas/DaysOff"},"bridgeDays":{"type":"integer","description":"Working days wedged between a holiday and a weekend.","example":0},"halfDays":{"type":"integer","description":"Days customarily worked as half days.","example":0}},"required":["from","to","calendarDays","duration","workingDays","daysOff","bridgeDays","halfDays"],"description":"The period between the date asked about and the answer, both endpoints counted. Null when that period spans more than 200 years, which the summary is not computed over — the period here is a consequence of the shift rather than the question, so it is left out rather than made an error."},"ObservanceList":{"type":"object","properties":{"count":{"type":"integer","description":"Number of entries in the list below.","example":13},"observances":{"type":"array","items":{"$ref":"#/components/schemas/ObservanceInfo"}}},"required":["count","observances"]},"ObservanceInfo":{"type":"object","properties":{"code":{"type":"string","example":"ascensionDay"},"holidayType":{"type":"string","enum":["public","defacto"],"description":"A public holiday is one under the Swedish Public Holidays Act (1989:253). A de facto holiday is not, but is treated as one in practice. Note that de facto does not mean unrecognised in law: Midsummer Eve, Christmas Eve and New Year's Eve are equated with Sunday by the Annual Leave Act (1977:480) s. 3 a and by the Act on the Calculation of Statutory Time (1930:173) s. 2. Easter Eve and Whitsun Eve rest on custom, and always fall on a Saturday."},"name":{"$ref":"#/components/schemas/Names"},"feast":{"$ref":"#/components/schemas/Feast"},"since":{"type":"integer","description":"First year the day was a holiday, when it has not always been one.","example":2005},"until":{"type":"integer","description":"Last year the day was a holiday, when it has since been abolished.","example":2004}},"required":["code","holidayType","name","feast"]},"OccurrenceList":{"allOf":[{"$ref":"#/components/schemas/ObservanceInfo"},{"type":"object","properties":{"count":{"type":"integer","description":"Number of entries in the list below.","example":13},"occurrences":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","example":2026},"day":{"$ref":"#/components/schemas/Day"}},"required":["year","day"]}}},"required":["count","occurrences"]}]}},"parameters":{}},"paths":{"/v3/holidays":{"get":{"summary":"Holidays for a year","description":"Public and de facto holidays, one entry per date. Two holidays can share a date, in which case the day carries two observances.","tags":["Holidays"],"parameters":[{"schema":{"type":"integer","minimum":1930,"maximum":9999,"description":"Year to look up, 1930–9999. Defaults to the current year in Sweden.","example":2026},"required":false,"description":"Year to look up, 1930–9999. Defaults to the current year in Sweden.","name":"year","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include Sundays, which are public holidays under the Swedish Public Holidays Act. Off by default: they are rarely what you are asking about.","example":"false"},"required":false,"description":"Include Sundays, which are public holidays under the Swedish Public Holidays Act. Off by default: they are rarely what you are asking about.","name":"sundays","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include Saturdays. They are days off in practice but are not public holidays in law.","example":"false"},"required":false,"description":"Include Saturdays. They are days off in practice but are not public holidays in law.","name":"saturdays","in":"query"}],"responses":{"200":{"description":"Holidays for the requested year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidaysResponse"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/bridge-days":{"get":{"summary":"Bridge days for a year","description":"Working days wedged between two days off – the Swedish \"klämdag\". Returned as ordinary days, so they carry workingDay: true and an empty observance list.","tags":["Holidays"],"parameters":[{"schema":{"type":"integer","minimum":1930,"maximum":9999,"description":"Year to look up, 1930–9999. Defaults to the current year in Sweden.","example":2026},"required":false,"description":"Year to look up, 1930–9999. Defaults to the current year in Sweden.","name":"year","in":"query"}],"responses":{"200":{"description":"Bridge days for the requested year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BridgeDaysResponse"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/half-days":{"get":{"summary":"Half days for a year","description":"Working days before a public holiday, when many workplaces finish early – the Swedish \"halvdag\".","tags":["Holidays"],"parameters":[{"schema":{"type":"integer","minimum":1930,"maximum":9999,"description":"Year to look up, 1930–9999. Defaults to the current year in Sweden.","example":2026},"required":false,"description":"Year to look up, 1930–9999. Defaults to the current year in Sweden.","name":"year","in":"query"}],"responses":{"200":{"description":"Half days for the requested year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HalfDaysResponse"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/days/{date}":{"get":{"summary":"A single day","description":"Looks up one date. Ordinary working days are returned with a null classification and no observances – the date exists, it is simply not a holiday. Takes no weekend flags: a Sunday is a public holiday whether or not you asked for Sundays.","tags":["Holidays"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date in ISO 8601 format.","example":"2026-06-06"},"required":true,"description":"Date in ISO 8601 format.","name":"date","in":"path"}],"responses":{"200":{"description":"The requested day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Day"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/period":{"get":{"summary":"Describe a period","description":"Everything Dagsmart knows about the days between two dates, in numbers: how many there are, how they read as calendar units, how many are working days, and how the days off divide up. One parameter decides which endpoints count, and every number in the response describes that same period.","tags":["Period"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First date of the period.","example":"2026-03-01"},"required":true,"description":"First date of the period.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last date of the period.","example":"2026-03-31"},"required":true,"description":"Last date of the period.","name":"to","in":"query"},{"schema":{"type":"string","enum":["inclusive","exclusive","from","to"],"description":"Which endpoints the period includes. \"inclusive\" counts both dates, \"exclusive\" neither, \"from\" only the start date, \"to\" only the end date. Defaults to inclusive, and governs every number in the response.","example":"inclusive"},"required":false,"description":"Which endpoints the period includes. \"inclusive\" counts both dates, \"exclusive\" neither, \"from\" only the start date, \"to\" only the end date. Defaults to inclusive, and governs every number in the response.","name":"bounds","in":"query"}],"responses":{"200":{"description":"The period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Period"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/shift":{"get":{"summary":"Move a date","description":"Answers \"what date is one month and three working days from here\". Steps are applied in the order given, each with its own result, because the order changes the answer. The Sunday rule is a choice, applied once to the whole chain.","tags":["Shift"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date to move from.","example":"2026-01-30"},"required":true,"description":"The date to move from.","name":"date","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^-?\\d+[dbwmy](,-?\\d+[dbwmy])*$"},{"type":"array","items":{"type":"string","pattern":"^-?\\d+[dbwmy](,-?\\d+[dbwmy])*$"},"minItems":1}],"description":"A step, as an amount and a unit: d days, b working days, w weeks, m months, y years. Negative moves backwards. Repeat the parameter for a chain — order matters, and it is applied in the order given. At most 20 steps.","example":"1m"},"required":true,"description":"A step, as an amount and a unit: d days, b working days, w weeks, m months, y years. Negative moves backwards. Repeat the parameter for a chain — order matters, and it is applied in the order given. At most 20 steps.","name":"add","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Apply the Sunday rule, s. 2 of the Act on the Calculation of Statutory Time (1930:173): a deadline landing on a day that is not a working day moves to the next one. Off by default, and applied once to the chain rather than to each step.","example":"false"},"required":false,"description":"Apply the Sunday rule, s. 2 of the Act on the Calculation of Statutory Time (1930:173): a deadline landing on a day that is not a working day moves to the next one. Off by default, and applied once to the chain rather than to each step.","name":"postpone","in":"query"}],"responses":{"200":{"description":"The chain, and where it ends.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shift"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v3/observances":{"get":{"summary":"All observances","description":"Every named holiday Dagsmart knows, with the years it applied. Weekends are not listed: they are properties of a date, not feasts.","tags":["Observances"],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObservanceList"}}}}}}},"/v3/observances/{code}":{"get":{"summary":"When an observance falls","description":"Occurrences for a year or a series of years. Years when the day was not a holiday are left out, so the series can be shorter than the range.","tags":["Observances"],"parameters":[{"schema":{"type":"string","description":"Observance code, as listed by /v3/observances.","example":"ascensionDay"},"required":true,"description":"Observance code, as listed by /v3/observances.","name":"code","in":"path"},{"schema":{"type":"integer","minimum":1930,"maximum":9999,"description":"First year. Defaults to the current year.","example":2026},"required":false,"description":"First year. Defaults to the current year.","name":"from","in":"query"},{"schema":{"type":"integer","minimum":1930,"maximum":9999,"description":"Last year. Defaults to the same year as `from`.","example":2030},"required":false,"description":"Last year. Defaults to the same year as `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"The observance and when it falls.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OccurrenceList"}}}},"400":{"description":"The request was not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No observance has that code.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{}}