{ "openapi": "3.1.1", "info": { "title": "Skyfold Meteor Shower Calendar API", "version": "1.0.0", "summary": "Every meteor shower of a year for your place: peak, Moon interference and the best hours.", "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://skyfoldmeteorshowers.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Every meteor shower of a year for your place: peak, Moon interference and the best hours.", "description": "Lists the meteor showers of a year with the moment of maximum, the night to watch, how high the radiant climbs, how much the Moon spoils the view and the expected number of meteors per hour at the best time for your place and sky, plus an .ics calendar of the best windows.\n\nMethodology:\n- Maximum: the instant the Sun reaches the solar longitude (equinox J2000.0) of the IMO working list, from the VSOP87 Sun minus the general precession in longitude; the 2026 IMO times are reproduced to within 5 minutes.\n- The night of the maximum is sampled every 20 minutes. Hourly rate HR = ZHR · sin(radiant altitude) / r^(6.5 − LM), counted only while the Sun is 12° or more below the horizon.\n- LM (limiting magnitude) comes from the sky brightness of your sky class plus the moonlight of Krisciunas \u0026 Schaefer (1991) at the zenith, converted with the Unihedron (after Schaefer 1990) formula.\n- Moon interference = share of the night’s meteors lost to moonlight. The best window covers the hours with at least 70 % of the best rate.\n\nRates are averages for an observer with a clear, open sky; real showers vary from year to year, and outbursts (for example of the Draconids or Leonids) are not predicted. Sporadic meteors (a few per hour) come on top.", "tags": [ "apps" ], "x-mcp-tool": "skyfold_meteor_showers", "x-owner-app": "skyfold", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkyfoldMeteorShowersInput" }, "examples": { "example1": { "summary": "Utrecht, 2026, rural sky", "value": { "location": "52.0907, 5.1214", "timeZone": "Europe/Amsterdam", "year": 2026, "sky": "rural", "showers": "major", "detail": "PER" } }, "example2": { "summary": "Sydney, 2027, every shower from a dark site", "value": { "location": "-33.8688, 151.2093", "elevation": 58, "timeZone": "Australia/Sydney", "year": 2027, "sky": "dark", "showers": "all", "detail": "ETA" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkyfoldMeteorShowersResult" } } } }, "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" } } } } } }, "SkyfoldMeteorShowersInput": { "type": "object", "additionalProperties": false, "properties": { "location": { "title": "Location (latitude, longitude)", "description": "Decimal degrees such as 52.09, 5.12 (north and east positive), or DMS, UTM, MGRS, Maidenhead or a plus code.", "type": "string", "maxLength": 80, "default": "52.0907, 5.1214" }, "elevation": { "title": "Elevation above sea level", "type": "number", "minimum": -500, "maximum": 9000, "default": 0, "x-unit": "m" }, "timeZone": { "title": "Time zone", "description": "IANA name such as Europe/Berlin or America/New_York, or a fixed offset such as UTC+2.", "type": "string", "maxLength": 64, "default": "Europe/Amsterdam" }, "year": { "title": "Year", "type": "integer", "minimum": 2000, "maximum": 2100, "default": 2026 }, "sky": { "title": "Your sky", "description": "Light pollution sets how many faint meteors you can see; the Moon is added on top.", "type": "string", "enum": [ "dark", "rural", "suburban", "city" ], "default": "rural" }, "showers": { "title": "Showers", "type": "string", "enum": [ "major", "all" ], "default": "major" }, "detail": { "title": "Hour-by-hour table for", "type": "string", "enum": [ "", "QUA", "ACE", "LYR", "PPU", "ETA", "ELY", "JBO", "JPE", "GDR", "SDA", "CAP", "PER", "KCG", "AUR", "SPE", "DRA", "STA", "ORI", "NTA", "LEO", "PUP", "HYD", "GEM", "URS", "COM" ], "default": "" } }, "required": [] }, "SkyfoldMeteorShowersResult": { "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" }, "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" } } } } } } } }