{ "openapi": "3.1.1", "info": { "title": "Printable Calendar Maker API", "version": "1.0.0", "summary": "Month or year calendars in 17 languages with week numbers and public holidays.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://printshopcalendar.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Month or year calendars in 17 languages with week numbers and public holidays.", "description": "Make a printable calendar for any year: one month per page or the whole year on one page, in 17 languages including right-to-left Arabic, with ISO 8601 or US week numbers, the first weekday of the region and public holidays for 16 countries (2024–2030).\n\nMethodology:\n- Month grids use the proleptic Gregorian calendar in UTC. The first weekday follows CLDR week data for the region (for example Sunday in the US, Monday in Germany, Saturday in Egypt) unless you choose one.\n- ISO 8601 weeks start on Monday and week 1 contains the year’s first Thursday; a row shows the ISO week of its Monday. US weeks start on Sunday and week 1 contains 1 January; a row shows the US week of its Saturday.\n- Month and weekday names come from the CLDR data built into the JavaScript runtime (Intl.DateTimeFormat). Arabic calendars run right to left. Text is shaped and embedded with Noto fonts.\n- Public holidays come from the RuleDate data set (Nager.Date) for 16 countries, 2024–2030; regional holidays need an ISO 3166-2 region code.\n\nHoliday data covers 2024–2030 and nationwide plus listed regional holidays; school holidays and local observances are not included. Check dates that matter.", "tags": [ "apps" ], "x-mcp-tool": "printshop_calendar", "x-owner-app": "printshop", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintshopCalendarInput" }, "examples": { "example1": { "summary": "German 2027 wall calendar with ISO weeks and Bavarian holidays", "value": { "year": 2027, "lang": "de", "country": "DE", "subdivision": "DE-BY", "weekNumbers": "iso" } }, "example2": { "summary": "US year at a glance on Letter landscape", "value": { "year": 2027, "layout": "year", "country": "US", "paper": "letter", "orientation": "landscape", "weekNumbers": "us" } }, "example3": { "summary": "Arabic six-month calendar", "value": { "year": 2027, "months": 6, "lang": "ar", "weekStart": "sat" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintshopCalendarResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "PrintshopCalendarInput": { "type": "object", "additionalProperties": false, "properties": { "year": { "title": "Year", "type": "integer", "minimum": 1900, "maximum": 2200, "default": 2027 }, "startMonth": { "title": "First month", "type": "integer", "minimum": 1, "maximum": 12, "default": 1 }, "months": { "title": "Number of months", "type": "integer", "minimum": 1, "maximum": 24, "default": 12 }, "layout": { "title": "Layout", "type": "string", "enum": [ "month", "year" ], "default": "month" }, "lang": { "title": "Language of month and day names", "type": "string", "enum": [ "en", "de", "fr", "es", "it", "pt", "nl", "pl", "tr", "ru", "uk", "ar", "hi", "zh", "ja", "ko", "id" ], "default": "en" }, "country": { "title": "Public holidays", "type": "string", "enum": [ "none", "DE", "AT", "CH", "US", "GB", "FR", "NL", "BE", "ES", "IT", "PL", "SE", "DK", "IE", "CA", "AU" ], "default": "none" }, "subdivision": { "title": "Region (optional)", "description": "ISO 3166-2 code such as DE-BY, CH-ZH or US-CA for regional holidays.", "type": "string", "maxLength": 10, "default": "" }, "localNames": { "title": "Holiday names in the local language", "type": "boolean", "default": true }, "weekStart": { "title": "First day of the week", "type": "string", "enum": [ "auto", "mon", "sun", "sat" ], "default": "auto" }, "weekNumbers": { "title": "Week numbers", "type": "string", "enum": [ "none", "iso", "us" ], "default": "none" }, "paper": { "title": "Paper size", "type": "string", "enum": [ "a3", "a4", "a5", "a6", "b5", "letter", "legal", "tabloid", "halfletter" ], "default": "a4" }, "orientation": { "title": "Orientation", "type": "string", "enum": [ "portrait", "landscape" ], "default": "portrait" }, "accent": { "title": "Accent colour", "type": "string", "maxLength": 7, "default": "#1f6f8b" }, "title": { "title": "Title (optional)", "type": "string", "maxLength": 120, "default": "" }, "notes": { "title": "Notes lines under each month", "type": "boolean", "default": true } }, "required": [] }, "PrintshopCalendarResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "year", "months", "firstWeekday", "holidays", "holidayDataCovers", "pages", "pageWidthMm", "pageHeightMm", "warnings", "files", "openInApp" ], "properties": { "year": { "type": "integer" }, "months": { "type": "integer" }, "firstWeekday": { "type": "string" }, "holidayDataCovers": { "type": "boolean" }, "holidays": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "name" ], "properties": { "date": { "type": "string" }, "name": { "type": "string" } } } }, "pages": { "type": "integer" }, "pageWidthMm": { "type": "number" }, "pageHeightMm": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "string" } }, "files": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "pdf", "svg", "png" ], "properties": { "pdf": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "svg": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "png": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } } } }, "openInApp": { "type": [ "string", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }