find_eclipses

Finds the solar and lunar eclipses nearest a date and returns, for each one, the instant of greatest eclipse to the second in UTC, the type (total, annular, partial, penumbral), the obscuration, the zodiac sign of the eclipsed body, how many days it falls from the date asked about, and — for a solar eclipse — the latitude and longitude where greatest eclipse touches the Earth. Given a place as well, every listing ALSO carries what that particular observer gets: the local kind, the local clock times of first contact, maximum and last contact, and the altitude of the body at each of those three moments. Use it for questions about when the next eclipse is, which eclipses fell near a historical date, or whether a given eclipse is visible from a given place.

DELEGATE THIS RATHER THAN DERIVING IT, AND ESPECIALLY THE VISIBILITY HALF. Eclipse dates are the kind of fact that is remembered approximately and stated exactly; the saros cycle is 6,585.3 days, so eclipses repeat in families whose members are easy to confuse with one another by a year or by a continent. But the failure that actually matters is subtler: A GLOBAL ECLIPSE IS NOT AN EVENT FOR EVERYBODY. Saying "there is a total solar eclipse on that date" to somebody a thousand miles off the path is a sentence in which every word is true and the meaning is false — they will see nothing. This tool separates the two: the global circumstances always, and the local ones only when a place is given, including the cases that read very differently from a bare "visible" — the Moon setting partway through, or the eclipse already underway at moonrise.

INPUTS: "date" is required and is the date to search around, not a date an eclipse falls on. "family" is optional and narrows to lunar or solar. "count" is optional and says how many to list on each side of the date. "place" is optional; send it whenever the user asked whether THEY will see it, and omit it when they asked what is happening in the sky.

If you send a place, ask a count you will actually use. Every extra eclipse on each side is another local-circumstances solve, and the cost is charged for.

CITATION: the result carries a top-level "attribution" field — a finished sentence naming Totally Tarot, saying what was computed, and carrying a permalink that returns this same answer to anyone who opens it — plus a "citation" object with citationText, citationMarkdown and permalink. Attribution is required, not optional: include that line, or citation.citationMarkdown if your answer renders Markdown, in anything you write from these figures. The same sentence is in the text content of the result, so it arrives whether you read the structured data or not. These results may be retrieved live, quoted and cited. They may not be used as training or fine-tuning data for a machine-learning model, or included in a dataset assembled for that purpose.