Moon & Star Map

Use this when the user wants a star map or night sky poster for a date and place: the sky over a city on a birthday, wedding, anniversary or the night they met, or the sky tonight. Computes the real positions of about 2,900 stars, constellation lines and the Moon for the city's local time (time zones and DST handled) and returns a preview plus vector poster PDFs (12x18 in, 18x24 in, A3, Letter, A4) and SVG. Takes a city name, not coordinates. Does not draw planets and is not for navigation or telescope pointing.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "City the sky is seen from, with state or country if ambiguous, e.g. \"Austin, Texas\", \"Paris, France\", \"Kraków\". Not coordinates."
    },
    "date": {
      "type": "string",
      "maxLength": 40,
      "description": "Local date YYYY-MM-DD, e.g. 2019-06-21, or \"tonight\" for the sky tonight."
    },
    "time": {
      "description": "Local clock time HH:MM (24 h) or 9:30 pm, e.g. 22:15. Default 21:00.",
      "type": "string",
      "maxLength": 16
    },
    "title": {
      "description": "Poster headline, e.g. \"The night we met\".",
      "type": "string",
      "maxLength": 80
    },
    "message": {
      "description": "Short line under the title, e.g. \"Under these stars, forever began\".",
      "type": "string",
      "maxLength": 160
    },
    "theme": {
      "description": "Colour style: midnight (navy and gold, default), black, paper (cream with a navy sky disc), ink (white, printer-friendly).",
      "type": "string",
      "enum": [
        "midnight",
        "black",
        "paper",
        "ink"
      ]
    },
    "constellations": {
      "description": "Draw constellation lines, e.g. true (default).",
      "type": "boolean"
    },
    "labels": {
      "description": "Label the brightest stars and constellations, e.g. false (default, cleaner keepsake look).",
      "type": "boolean"
    },
    "show_moon": {
      "description": "Draw the Moon in its real position and phase when it is above the horizon, e.g. true (default).",
      "type": "boolean"
    }
  },
  "required": [
    "city",
    "date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "place": {
      "type": "string"
    },
    "coordinates": {
      "type": "string"
    },
    "local_time": {
      "type": "string"
    },
    "utc_time": {
      "type": "string"
    },
    "time_zone": {
      "type": "string"
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "stars_drawn": {
      "type": "number"
    },
    "brightest_visible": {
      "type": "array",
      "items": {}
    },
    "constellations_visible": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "moon": {},
    "downloads": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "request": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "place",
    "coordinates",
    "local_time",
    "utc_time",
    "time_zone",
    "notes",
    "stars_drawn",
    "brightest_visible",
    "constellations_visible",
    "moon",
    "downloads",
    "request"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user asks what the moon looked like on a date (birthday, wedding, first date), the moon phase today or tonight, whether two people's birthday moons complete each other ("our moons make a full moon"), or wants a moon phase calendar for a month. Returns phase name, illumination %, moon age, waxing/waning, exact phase times and the next full and new moon, computed with astronomical algorithms. Does not give astrology readings, tides or moonrise times. Do not use for planets or eclipses.

{
  "type": "object",
  "properties": {
    "dates": {
      "description": "Dates to look up as YYYY-MM-DD, optionally with a local time YYYY-MM-DDTHH:MM, e.g. [\"1998-07-14\"] for a birthday or [\"1996-05-02\", \"1997-11-20\"] for a couple. Omit for the Moon right now.",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "labels": {
      "description": "Optional names for the dates in the same order, e.g. [\"Anna\", \"Ben\"].",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "month": {
      "description": "A month YYYY-MM for a moon-phase calendar of every day plus the exact new, quarter and full moon times, e.g. 2026-01.",
      "type": "string",
      "maxLength": 24
    },
    "city": {
      "description": "City (with state or country if ambiguous) that sets the time zone and hemisphere, e.g. \"Austin, Texas\" or \"Sydney, Australia\". Without it, dates are read in UTC.",
      "type": "string",
      "maxLength": 120
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "place": {
      "type": [
        "string",
        "null"
      ]
    },
    "time_zone": {
      "type": "string"
    },
    "hemisphere": {
      "type": "string"
    },
    "note": {
      "type": "string"
    },
    "moons": {
      "type": "array",
      "items": {}
    },
    "pair": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "calendar": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "place",
    "time_zone",
    "hemisphere",
    "note",
    "moons",
    "pair",
    "calendar"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when the user wants a printable moon phase poster: the moon on one special date, two dates side by side ("our moons" couple print), or a lunar calendar of a whole year. Computes the real phases and returns a preview plus vector PDFs (12x18 in, 18x24 in, A3, Letter, A4) and SVG. Does not sell or ship prints. Do not use for a quick phase answer without a poster; that is find_moon_phase.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "moon",
        "pair",
        "year"
      ],
      "description": "moon: one date's moon as a large print; pair: two dates side by side (e.g. two birthdays) with whether they complete each other; year: a lunar calendar of all 365 days. Example: pair."
    },
    "dates": {
      "description": "For moon: one date; for pair: two dates. YYYY-MM-DD, optionally with a local time YYYY-MM-DDTHH:MM, e.g. [\"1995-03-14\", \"1996-09-02\"].",
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "labels": {
      "description": "Optional names under each moon for pair, e.g. [\"Mia\", \"Leo\"].",
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "year": {
      "description": "For year: the calendar year, e.g. 2027.",
      "type": "integer",
      "minimum": 1800,
      "maximum": 2200
    },
    "city": {
      "description": "City for the time zone and hemisphere (southern hemisphere moons are drawn mirrored), e.g. \"Melbourne, Australia\". Default UTC.",
      "type": "string",
      "maxLength": 120
    },
    "title": {
      "description": "Poster headline, e.g. \"The moon on the day you were born\".",
      "type": "string",
      "maxLength": 80
    },
    "message": {
      "description": "Short line under the title, e.g. \"Mia, 14 March 1995\".",
      "type": "string",
      "maxLength": 160
    },
    "theme": {
      "description": "midnight (default), black, paper, or ink.",
      "type": "string",
      "enum": [
        "midnight",
        "black",
        "paper",
        "ink"
      ]
    }
  },
  "required": [
    "kind"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    },
    "moons": {
      "type": "array",
      "items": {}
    },
    "pair": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "downloads": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "request": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "kind",
    "summary",
    "moons",
    "pair",
    "downloads",
    "request"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}