Find passes
find_passesList every upcoming pass of one satellite over a location in the next windowHours (default 48, up to 240), in time order. Each pass has rise/peak/set times (UTC, plus riseLocal etc. on the observer's clock), peak elevation, azimuths with compass words (direction), the range at the peak (peakRangeKm), duration, brightness (magnitude, lower is brighter; peakMagnitudeEstimated means no measured magnitude is known for it, so it is a cautious guess; most of the bright satellites have a measured one, and a Starlink still flying in its launch train uses a typical train brightness, a rule of thumb rather than a measurement), and when it can be seen by eye: visibleFrom/visibleUntil (null if never on that pass) plus leavesShadow/entersShadow when it appears or fades mid-sky. rating is the rating seeksat.com shows for the pass: { word (Poor, Fair, Good, Great, Excellent), bars (1-5), level (low, ok, good), reason }. In visual mode it is how much brighter than the faintest visible star the pass gets for skyType (headroomMag), stepped down for a cloudy forecast up to 4 days ahead, and no higher than Fair when the brightness is estimated; in radio mode it is the peak height, a bar lower for each 6 dB of extra path loss when the satellite is more than 2,000 km away at the peak (8,000 km costs two bars), and no higher than Fair when SatNOGS stations tried at least 3 times in 30 days and heard nothing (the result then carries the satellite's reception and receptionSource). captureProbability (0-1) is the chance a camera captures the pass: sky darkness, height, clear-sky odds and length, with brightness playing no part; quality is its old name, the same number. Rise and set are when it crosses minElevation, not the horizon. In visual mode rise and set are the part of the pass that can be seen, so they can start or end mid-sky, and peak, peakElevationDeg and direction.peak are the highest point of that part (the whole pass may climb higher). passUrl opens that pass on seeksat.com, from that place, to hand to the user. In visual mode it fetches the cloud forecast for the place, as best_pass does (weather says whether one was used). This is the tool for comparing passes or finding the best or brightest one over a span of days, not just the next. An empty list comes with a note saying why (it never rises high enough from that latitude, the sky never gets dark, and so on). Feed a pass's peak time to get_pass_chart (to draw it) or get_pass_weather (to check clouds). To rank passes across many satellites at once, use best_pass.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"satellite": "<satellite>"
},
"name": "find_passes"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead. | |
| lon | No | observer longitude in decimal degrees, east positive and west negative (-180 to 180). | |
| mode | No | "visual" (default): naked-eye passes, sunlit while the sky is dark; "radio": every line-of-sight pass, day or night. | |
| minElev | No | old name for minElevation; still accepted. | |
| skyType | No | how dark the observer's sky is, for the visual rating as on seeksat.com: "city" (stars to magnitude 3.5), "suburban" (stars to magnitude 4.5), "rural" (stars to magnitude 5.5), "dark" (stars to magnitude 6.5). Default "suburban". | |
| location | No | where the observer is, when lat and lon are not given (they win when both are): a Maidenhead grid square (EN52, EN52ve, EN52ve12), coordinates in any common form ("41.88, -87.63", "41.88N 87.63W", "41°52'48"N 87°37'48"W", a Google Maps link or geo: URI), all read locally, or a place name (city, address, landmark) looked up with OpenStreetMap. Prefer lat and lon, or a grid square, when you have them: a place name is a network lookup. | |
| satellite | Yes | NORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss". | |
| windowHours | No | how far ahead to look, in hours, up to 240 (10 days). Default 48. | |
| minElevation | No | lowest elevation that counts: a pass must climb above it, and rise and set are when it crosses it, in degrees above the horizon (0 to 90). Default 10. | |
| minElevationDeg | No | old name for minElevation; still accepted. |