Best pass
best_passFind the best upcoming pass(es) over a location, ranked by the rating seeksat.com shows ("what's the best pass tonight?"). Give satellite to rank that one satellite's passes. Omit it to scan: in visual mode (default) the popular satellites plus every satellite in CelesTrak's visual group (the brightest objects in the sky, about 160, many of them spent rocket bodies), over 72 hours by default (168 at most); in radio mode every satellite with known downlinks (about a thousand), optionally only those with a downlink in bands or of a kind in modes, over 24 hours by default (72 at most). A scan reports satellitesScanned, leaves out satellites whose orbital elements are more than 14 days old at the start (skippedStaleElements) and any pass more than 14 days from its satellite's elements, counts what else it skipped, and radio passes list the satellite's downlinks. Returns best (the top pass) plus a passes array of the top-ranked options, each tagged with its satellite. 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. Visual passes rank by rating bars, then a known brightness before an estimated one, then headroomMag, then captureProbability; the cloud forecast for the location is folded in where it reaches (cloudCoverPct at the peak; weather says whether a forecast was used). Radio scans rank satellites with a downlink a hobby receiver can tune (30 MHz to 1 GHz) ahead of the rest unless bands is given, then by rating bars, then how recently SatNOGS stations heard the satellite (last 48 hours, 7 days, 30 days, unknown, probably silent), then peak elevation, then captureProbability. A probably silent satellite (SatNOGS stations tried at least 3 times in 30 days and heard nothing) rates no higher than Fair; unknown is never held down. Radio rows carry the satellite's reception (its best downlink's). Downlinks carry reception from SatNOGS Network observations when known: { state (heard, silent: stations tried and heard nothing, or unknown: no observations, never a sign it is dead), heardLast48h, heardLast7d, heardLast30d, failedLast30d, lastHeard }, listed most recently heard first; receptionSource names the source (CC BY-SA 4.0). An empty result comes with a note saying why. Set chart:true to also render the winning pass's sky chart in this same call.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "best_pass"
}
}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. | |
| bands | No | radio scan only: keep satellites with a downlink in these bands: hf (3-30 MHz), wx (137 MHz weather), 2m (144-148 MHz), 70cm (420-450 MHz), l (1-2 GHz), s (2-4 GHz), other. Default: any band. | |
| chart | No | true to also render the winning pass's polar sky chart (PNG) and return it in this same result. Default false. | |
| limit | No | how many ranked passes to return, 1 to 20. Default 3. | |
| modes | No | radio scan only: keep satellites with a downlink of one of these kinds, matched on its mode or label, e.g. ["fm", "apt", "sstv"]. Default: any. | |
| 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 | No | NORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss". Omit to scan: visual mode scans the popular satellites plus CelesTrak's visual group, radio mode every satellite with known downlinks. | |
| windowHours | No | how far ahead to look, in hours, up to 240 (10 days). Default 72. With no satellite named, a visual scan stops at 168, and a radio scan defaults to 24 and stops at 72. | |
| 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. |