{ "openapi": "3.1.1", "info": { "title": "Skyfold Planet Conjunctions and Best Evenings API", "version": "1.0.0", "summary": "Close pairings of the Moon and planets and their best evenings for the next months, as a calendar.", "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://skyfoldconjunctions.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Close pairings of the Moon and planets and their best evenings for the next months, as a calendar.", "description": "Finds every close approach of the Moon, Mercury, Venus, Mars, Jupiter and Saturn, the oppositions of Mars to Neptune and the greatest elongations of Mercury and Venus, checks whether you can see them in the evening or morning twilight at your place and exports them as an .ics calendar.\n\nMethodology:\n- Apparent geocentric positions from the Skyfold ephemeris (VSOP87 planets with light time and aberration, ELP-2000/82 Moon); separations sampled every 12 hours (Moon pairs every 2 hours) and refined to the minute by golden-section search.\n- Oppositions: the planet’s ecliptic longitude differs from the Sun’s by 180°; greatest elongations: maxima of the Sun–planet angle for Mercury and Venus, east = evening sky.\n- Visible: at evening or morning civil twilight (Sun 6° down) the lower of the two objects stands at least 5° above the horizon and both are at least 12° from the Sun; the visible twilight closest to the event is suggested (with the separation at that moment), oppositions at the planet’s transit.\n- The 2026 results reproduce the published dates (Venus–Saturn 8 March, Venus–Jupiter 9 June 1.6°, Mercury–Jupiter 15 August, oppositions of Jupiter 10 January and Saturn 4 October).\n\nSeparations are geocentric; seen from your place the Moon shifts by up to 1° (parallax), so Moon pairings can look closer or wider, and close ones can become occultations for some regions.", "tags": [ "apps" ], "x-mcp-tool": "skyfold_conjunctions", "x-owner-app": "skyfold", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkyfoldConjunctionsInput" }, "examples": { "example1": { "summary": "Utrecht, 2026", "value": { "location": "52.0907, 5.1214", "timeZone": "Europe/Amsterdam", "startDate": "2026-01-01", "months": 12, "planetLimit": 3, "moonLimit": 3, "includeMoon": true, "visibleOnly": true } }, "example2": { "summary": "Buenos Aires, planets only, 2027", "value": { "location": "-34.6037, -58.3816", "elevation": 25, "timeZone": "America/Argentina/Buenos_Aires", "startDate": "2027-01-01", "months": 12, "planetLimit": 2, "moonLimit": 3, "includeMoon": false, "visibleOnly": true } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkyfoldConjunctionsResult" } } } }, "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" } } } } } }, "SkyfoldConjunctionsInput": { "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" }, "startDate": { "title": "From", "type": "string", "format": "date", "default": "2027-01-01" }, "months": { "title": "Months", "type": "integer", "minimum": 1, "maximum": 24, "default": 12 }, "planetLimit": { "title": "Closest planet pairs within", "type": "number", "minimum": 0.1, "maximum": 10, "default": 3, "x-unit": "°" }, "moonLimit": { "title": "Moon and planet within", "type": "number", "minimum": 0.1, "maximum": 10, "default": 3, "x-unit": "°" }, "includeMoon": { "title": "Include the Moon", "type": "boolean", "default": true }, "visibleOnly": { "title": "Only events visible from this place", "type": "boolean", "default": true } }, "required": [] }, "SkyfoldConjunctionsResult": { "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" } } } } } } } }