CycleCalcs Astronomy

{'type': 'object', 'anyOf': [{'required': ['lat', 'lon']}, {'required': ['place']}], 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'Night to start from. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'nights': {'type': 'integer', 'maximum': 62, 'minimum': 1, 'description': 'How many nights to evaluate and rank. Default 1.'}, 'moon_illumination_max': {'type': 'number', 'maximum': 1, 'minimum': 0, 'description': 'Treat the Moon as tolerable below this illuminated fraction (0..1) even when up.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'method': {'type': 'object', 'description': 'How darkness was defined and how nights were ranked.'}, 'nights': {'type': 'array', 'description': 'Each night with its dark window and what the Moon does to it.'}, 'ranked': {'type': 'array', 'description': 'Night indices best to worst.'}, 'summary': {'type': 'object', 'description': 'The recommendation in brief.'}, 'best_night_index': {'type': 'integer', 'description': 'Index into `nights` of the best one.'}, 'high_latitude_note': {'type': ['string', 'null'], 'description': 'The explanation when that caution is set.'}, 'high_latitude_caution': {'type': 'boolean', 'description': 'True when latitude makes true darkness scarce or absent, so the ranking means less.'}}, 'description': 'The best genuinely dark observing windows across a range of nights.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Last day of an explicit window. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'Anchor date to search from. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'type': {'enum': ['solar', 'lunar', 'both'], 'type': 'string', 'description': 'Which kind of eclipse to report. Default "both".'}, 'count': {'type': 'integer', 'minimum': 1, 'description': 'How many eclipses PER TYPE to return.'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'First day of an explicit window (use with end). ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}, 'include': {'type': 'array', 'items': {'enum': ['path', 'greatest'], 'type': 'string'}, 'description': 'Optional extras, added to the default blocks rather than replacing them. "path": the precomputed central path of a solar eclipse as inline GeoJSON (central line, northern and southern limits, and per-minute duration, width, phase and Sun altitude), for the central eclipses that have one; every other eclipse says why it has none. Large: about 65 to 90 KB of JSON per eclipse, returned as both text and structured content, so ask for one eclipse at a time (type "solar", a date just before it, count 1). "greatest": the circumstances at greatest eclipse from the supplied location, inside each solar eclipse\'s local block (requires a location).', 'uniqueItems': True}, 'direction': {'enum': ['next', 'previous'], 'type': 'string', 'description': 'Search direction from the anchor date. Default "next".'}, 'visible_only': {'type': 'boolean', 'description': 'true keeps only eclipses visible from the supplied location (requires a location).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'type': {'type': 'string', 'description': 'Which kinds were asked for: solar, lunar or both.'}, 'window': {'type': 'object', 'description': 'The range actually evaluated.'}, 'summary': {'type': 'string', 'description': 'A one-line reading of the range.'}, 'eclipses': {'type': 'array', 'description': 'Each eclipse with its peak instant, kind and Saros series. Solar rows also carry hybrid (true for an eclipse total along part of its central track and annular along the rest; kind keeps the value at greatest eclipse), hybrid_transitions, and greatest_eclipse_duration_seconds, greatest_eclipse_path_width_km and greatest_eclipse_sun_altitude_deg (null when there is no central line). With include path, each row has a path object: available, and when true an inline GeoJSON FeatureCollection.'}, 'next_visible': {'type': 'object', 'description': 'Only when a location was given: the next one visible from there, with local circumstances.'}, 'eclipse_count': {'type': 'integer', 'description': 'How many eclipses matched.'}, 'next_visible_note': {'type': 'string', 'description': 'Only when a location was given: a caveat about that visibility, when one applies.'}, 'central_geometry_note': {'type': 'string', 'description': 'Only when solar eclipses are listed: the lunar-radius convention behind hybrid, the greatest_eclipse fields and the path.'}}, 'description': 'Solar and lunar eclipses in a date range, optionally filtered to one location.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'A place_id from an earlier result, to fetch that exact place.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'limit': {'type': 'integer', 'maximum': 20, 'minimum': 1, 'description': 'Maximum matches to return. Default 5.'}, 'query': {'type': 'string', 'description': 'Place name to search for, e.g. "Springfield".'}, 'country': {'type': 'string', 'description': 'Two-letter ISO country code filter, e.g. "US".'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'mode': {'type': 'string', 'description': 'Whether this was a name search or a reverse lookup.'}, 'found': {'type': 'integer', 'description': 'How many are returned here.'}, 'index': {'type': 'object', 'description': 'Which place index answered, and its vintage.'}, 'matched': {'type': 'integer', 'description': 'How many places matched before any limit was applied.'}, 'results': {'type': 'array', 'description': 'Each place with coordinates, country, population and a place_id that other tools accept.'}}, 'description': 'Coordinates for a place name, or the nearest named places to coordinates.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Last day of a daily series. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'count': {'type': 'integer', 'minimum': 1, 'description': 'Number of daily rows from start (alternative to end).'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'First day of a daily series. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'phase': {'type': 'object', 'description': 'Phase name, angle and illuminated fraction.'}, 'series': {'type': 'array', 'description': 'RANGE MODE ONLY: one sampled entry per step.'}, 'window': {'type': 'object', 'description': 'The instant or range actually evaluated.'}, 'summary': {'type': 'string', 'description': 'A one-line reading of the Moon right now.'}, 'rise_set': {'type': 'object', 'description': 'Moonrise and moonset for the location.'}, 'libration': {'type': 'object', 'description': 'The rocking that reveals a little of the far side.'}, 'magnitude': {'type': 'number', 'description': 'Apparent visual brightness.'}, 'bright_limb': {'type': 'object', 'description': 'Which way the lit edge points.'}, 'distance_au': {'type': 'number', 'description': 'The same distance in astronomical units.'}, 'distance_km': {'type': 'number', 'description': 'Center-to-center distance in kilometres.'}, 'next_phases': {'type': 'array', 'description': 'Upcoming quarter phases with exact instants.'}, 'parallax_deg': {'type': 'number', 'description': 'Angular shift between those two viewpoints.'}, 'constellation': {'type': 'object', 'description': 'The IAU constellation the Moon currently occupies.'}, 'tropical_sign': {'type': 'object', 'description': 'Tropical ecliptic longitude, reported as position only.'}, 'distance_basis': {'type': 'string', 'description': 'Whether the distance is geocentric or topocentric.'}, 'event_definition': {'type': 'string', 'description': 'The altitude convention rise and set are measured against.'}, 'position_geocentric': {'type': 'object', 'description': "Position as seen from Earth's center."}, 'position_topocentric': {'type': 'object', 'description': 'Position as seen from the given location.'}, 'angular_diameter_arcsec': {'type': 'number', 'description': 'Apparent disk size in arcseconds.'}, 'fraction_of_mean_distance': {'type': 'number', 'description': 'Distance relative to the mean, for supermoon claims.'}, 'fraction_of_mean_distance_definition': {'type': 'string', 'description': 'How that fraction is defined.'}}, 'description': "The Moon's state and appearance, or a sampled series in range mode.", 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Last day of a window. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'Anchor date; the next phases follow it. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'count': {'type': 'integer', 'minimum': 1, 'description': 'How many phase events to return from the anchor date.'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'First day of a window (use with end). ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}, 'phases': {'type': 'array', 'items': {'enum': ['new_moon', 'first_quarter', 'full_moon', 'last_quarter'], 'type': 'string'}, 'minItems': 1, 'description': 'Optional filter of phase kinds. Omit for all four. Example: ["full_moon"] for full moons only.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'phases': {'type': 'array', 'description': 'Each phase with its exact instant and name.'}, 'window': {'type': 'object', 'description': 'The range actually evaluated.'}, 'summary': {'type': 'string', 'description': 'A one-line reading of the range.'}, 'phase_count': {'type': 'integer', 'description': 'How many phases fall in the window.'}}, 'description': 'New, first quarter, full and last quarter moons in a date range.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'sort': {'enum': ['distance_from_sun', 'magnitude', 'elongation', 'altitude'], 'type': 'string', 'description': 'Optional result ordering. Default is by distance from the Sun.'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'bodies': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 8, 'minItems': 1, 'description': 'Optional subset of planets: mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'count': {'type': 'integer', 'description': 'How many bodies are on the board.'}, 'bodies': {'type': 'array', 'description': 'Every body with position, brightness and a visibility verdict.'}, 'instant': {'type': 'string', 'description': 'The moment evaluated.'}, 'summary': {'type': 'string', 'description': "A one-line reading of tonight's planets."}, 'observable_now': {'type': 'array', 'description': 'Bodies both up and realistically visible.'}, 'retrograde_now': {'type': 'array', 'description': 'Bodies currently in apparent retrograde motion.'}, 'above_horizon_now': {'type': 'array', 'description': 'Bodies above the horizon, visible or not.'}}, 'description': 'Which planets are worth looking at right now, and where.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Last day of an explicit window, exclusive. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'Anchor instant; with no start/end the response covers the next full synodic cycle from here. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'kinds': {'type': 'array', 'items': {'enum': ['inferior_conjunction', 'superior_conjunction', 'greatest_elongation_east', 'greatest_elongation_west', 'peak_magnitude', 'transit_of_mercury', 'transit_of_venus', 'conjunction_with_sun', 'quadrature_west', 'opposition', 'quadrature_east', 'constellation_entry'], 'type': 'string'}, 'minItems': 1, 'description': "Optional filter of event kinds. Omit for each planet's own family: the seven apparition kinds for mercury and venus, the four Sun-relative kinds for mars to neptune. peak_magnitude only ever fires for venus; the transit kinds are body-specific and genuinely rare. constellation_entry applies to all seven and must be listed."}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'First day of an explicit window (use with end). ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'bodies': {'type': 'array', 'items': {'enum': ['mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'], 'type': 'string'}, 'maxItems': 7, 'minItems': 1, 'description': 'Which planets to report. Default mercury and venus.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'bodies': {'type': 'array', 'description': 'One entry per body, each holding its events in time order.'}, 'window': {'type': 'object', 'description': 'The range actually evaluated.'}, 'body_count': {'type': 'integer', 'description': 'How many bodies are covered.'}, 'definition': {'type': 'string', 'description': 'How each event kind is defined.'}, 'event_count': {'type': 'integer', 'description': 'How many events matched in total.'}, 'kinds_selected': {'type': 'array', 'description': 'The event kinds included.'}}, 'description': "Planet events in a date range: the Mercury and Venus apparition events (conjunctions, greatest elongations, Venus's peak brightness, transits across the Sun), the Sun-relative events of Mars to Neptune (conjunction with the Sun, quadratures, opposition) and, when asked for, constellation entries. Stations (retrograde turning points) are not among them: astro_planet_board gives each planet's next station, and the full station list is served by the REST route /v2/retrogrades.", 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'required': ['bodies'], 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Grid end. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'step': {'type': 'string', 'description': 'Grid stride, e.g. "1h", "10min", "1d".'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'Grid start (use with end and step). ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'bodies': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 20, 'minItems': 1, 'description': 'Bodies to report. Each entry: One of sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, or a fixed J2000 target as "radec:RA,DEC" with RA in hours (0-24) and DEC in degrees (-90..90), e.g. "radec:5.6,-5.4" for the Orion Nebula region.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'bodies': {'type': 'array', 'description': 'SINGLE MODE: one entry per body, with its coordinates.'}, 'series': {'type': 'array', 'description': 'RANGE MODE: one sample per step, each holding every body.'}, 'window': {'type': 'object', 'description': 'RANGE MODE: the range actually evaluated.'}, 'instant': {'type': 'string', 'description': 'SINGLE MODE: the instant evaluated.'}}, 'description': 'Where each requested body is, at an instant or sampled across a range.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'anyOf': [{'required': ['lat', 'lon']}, {'required': ['place']}], 'required': ['body'], 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Last day of a daily series. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'body': {'type': 'string', 'description': 'One of sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, or a fixed J2000 target as "radec:RA,DEC" with RA in hours (0-24) and DEC in degrees (-90..90), e.g. "radec:5.6,-5.4" for the Orion Nebula region.'}, 'date': {'type': 'string', 'description': 'ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'First day of a daily series. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}, 'search_horizon_days': {'type': 'integer', 'minimum': 1, 'description': 'How many days ahead to search when an event does not occur on the requested day (high latitudes).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'body': {'type': 'object', 'description': 'SINGLE MODE: the events, with a status covering the polar cases where a body never rises or never sets.'}, 'days': {'type': 'array', 'description': 'RANGE MODE ONLY: one entry per day.'}, 'window': {'type': 'object', 'description': 'The day or range actually evaluated.'}}, 'description': 'Rise, transit and set for one body, for a day or across a range.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'sun': {'type': 'object', 'description': "Sunrise, sunset and the Sun's current position."}, 'moon': {'type': 'object', 'description': 'Phase, illuminated fraction, and rise/set.'}, 'night': {'type': 'object', 'description': 'When true darkness begins and ends tonight.'}, 'summary': {'type': 'string', 'description': 'A one-line plain-language reading of the whole snapshot.'}, 'local_date': {'type': 'string', 'description': 'The local calendar date the snapshot describes.'}, 'planets_up': {'type': 'array', 'description': 'Planets above the horizon now, brightest first.'}, 'next_events': {'type': 'array', 'description': 'The next notable sky events, soonest first.'}, 'planets_down': {'type': 'array', 'description': 'Planets below the horizon now.'}}, 'description': 'A whole-sky snapshot for one place and moment.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}

{'type': 'object', 'anyOf': [{'required': ['lat', 'lon']}, {'required': ['place']}], 'properties': {'tz': {'type': 'string', 'description': 'IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.'}, 'end': {'type': 'string', 'description': 'Last day of a range. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'lat': {'type': 'number', 'maximum': 90, 'minimum': -90, 'description': 'Latitude in decimal degrees, north positive. Send lat and lon together.'}, 'lon': {'type': 'number', 'maximum': 180, 'minimum': -180, 'description': 'Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.'}, 'date': {'type': 'string', 'description': 'Single day to report, ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'step': {'type': 'string', 'description': 'Range stride in whole days, e.g. "1d", "7d", "30d". Default "1d".'}, 'place': {'type': 'string', 'description': 'Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.'}, 'start': {'type': 'string', 'description': 'First day of a range (use with end instead of date). ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.'}, 'cursor': {'type': 'string', 'description': "Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['data'], 'properties': {'data': {'type': 'object', 'properties': {'days': {'type': 'array', 'description': 'RANGE MODE ONLY: one entry per day, each with the fields above.'}, 'custom': {'type': 'array', 'description': 'Boundaries for any custom depression angles requested.'}, 'window': {'type': 'object', 'description': 'The instant or range actually evaluated, after parsing.'}, 'summary': {'type': 'string', 'description': 'A one-line reading of the solar day.'}, 'rise_set': {'type': 'object', 'description': 'Sunrise and sunset, with a status for polar day and polar night.'}, 'twilight': {'type': 'object', 'description': 'Civil, nautical and astronomical twilight boundaries.'}, 'blue_hour': {'type': 'object', 'description': 'The blue-light window just outside golden hour.'}, 'day_length': {'type': 'string', 'description': 'Day length, human-readable.'}, 'night_ends': {'type': ['string', 'null'], 'description': 'When astronomical night ends. Null where it never gets that dark.'}, 'solar_noon': {'type': 'string', 'description': 'Instant the Sun crosses the meridian.'}, 'golden_hour': {'type': 'object', 'description': 'The warm-light window around sunrise and sunset.'}, 'dark_minutes': {'type': 'integer', 'description': 'Minutes of true astronomical darkness.'}, 'night_begins': {'type': ['string', 'null'], 'description': 'When astronomical night starts. Null where it never gets that dark.'}, 'position_now': {'type': 'object', 'description': 'Where the Sun is at this moment.'}, 'constellation': {'type': 'object', 'description': 'The IAU constellation the Sun currently occupies.'}, 'tropical_sign': {'type': 'object', 'description': 'Tropical ecliptic longitude, reported as position only.'}, 'solar_midnight': {'type': 'string', 'description': 'Instant the Sun is lowest, opposite solar noon.'}, 'day_length_minutes': {'type': 'number', 'description': 'Day length in minutes.'}, 'day_length_seconds': {'type': 'integer', 'description': 'Day length in whole seconds.'}, 'solar_noon_azimuth_deg': {'type': 'number', 'description': 'Compass bearing of the Sun at solar noon.'}, 'solar_noon_altitude_deg': {'type': 'number', 'description': 'Sun altitude at solar noon, in degrees.'}, 'solar_midnight_altitude_deg': {'type': 'number', 'description': 'Sun altitude at solar midnight, in degrees.'}, 'solar_noon_altitude_refracted_deg': {'type': 'number', 'description': 'As seen, including atmospheric refraction.'}, 'solar_noon_altitude_unrefracted_deg': {'type': 'number', 'description': 'Geometric altitude, refraction excluded.'}, 'solar_midnight_altitude_refracted_deg': {'type': 'number', 'description': 'Including refraction.'}, 'solar_midnight_altitude_unrefracted_deg': {'type': 'number', 'description': 'Geometric, refraction excluded.'}, 'day_length_change_from_yesterday_seconds': {'type': 'integer', 'description': 'Seconds gained or lost since the previous day. Negative means shortening.'}}, 'description': 'The complete solar day for one location, or one row per day in range mode.', 'additionalProperties': True}, 'rights': {'type': 'string', 'description': 'Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.'}, 'warnings': {'type': 'array', 'description': 'Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.'}, 'attribution': {'type': 'string', 'description': 'The credit line to display verbatim when rights is attribution_required.'}, 'next_cursor': {'type': 'string', 'description': 'Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.'}, 'not_computed': {'type': 'array', 'description': 'Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".'}}, 'description': 'The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.', 'additionalProperties': True}