SeekSat

Dünya'nın her yerindeki uydu geçişleri: ne zaman ve nereye bakmalı, bulut tahminleri, o hareketli ışığın ne olduğu ve radyo Doppler etkisi.

Barındırılan MCP Sunucusu

npx add-mcp 'https://seeksat.com/api/mcp'

Claude Code, Codex, Cursor ve daha fazlasına kurulur

Dokümantasyon

Connect

Endpoint (Streamable HTTP, no sign-in):

https://seeksat.com/api/mcp

Claude Code

claude mcp add --transport http seeksat https://seeksat.com/api/mcp

Add --scope user to have it in every project. Or in a project's .mcp.json (a remote server needs "type": "http"):

{
  "mcpServers": {
    "seeksat": {
      "type": "http",
      "url": "https://seeksat.com/api/mcp"
    }
  }
}

Claude Desktop and claude.ai

Settings > Connectors > Add custom connector, name it SeekSat, and paste https://seeksat.com/api/mcp. No sign-in is needed.

Where custom connectors are not available, bridge it in claude_desktop_config.json with mcp-remote (needs Node.js):

{
  "mcpServers": {
    "seeksat": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://seeksat.com/api/mcp"
      ]
    }
  }
}

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "seeksat": {
      "url": "https://seeksat.com/api/mcp"
    }
  }
}

Access and limits

Free and open: no sign-up and no key needed, and every satellite is free. The server also reads an optional API key (Authorization: Bearer <key>, or X-API-Key: <key>) so keyed access can be added later without an API change.

To send a key from Claude Code:

claude mcp add --transport http seeksat https://seeksat.com/api/mcp --header "Authorization: Bearer YOUR_KEY"

From Cursor:

{
  "mcpServers": {
    "seeksat": {
      "url": "https://seeksat.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Up to 120 requests per 60 seconds per IP address (a firewall rule on the endpoint). Past that, requests are refused with HTTP 429 until the minute is up.

Errors

  • A tool that cannot answer (an unknown satellite, a place it cannot geocode, a time it cannot read) returns a normal tool result with isError: true and the text "Error: <message>", saying what to fix.
  • Inputs of the wrong type or out of range are refused before the tool runs. That is also a tool result with isError: true (not a JSON-RPC error), whose text starts "MCP error -32602: Input validation error" and names the field and its limit.
  • A parameter a tool does not take is refused the same way, with a message listing the ones it does take. Old parameter names still work on every tool that takes the parameter: minElevationDeg and minElev for minElevation; passTime for time.

Tools

ToolWhat it does
list_satellitesThe popular satellites (ISS, Tiangong, Hubble and a few more) with each one's orbit data freshness.
find_passesUpcoming passes of one satellite or several over a place, in time order, from the next pass to the full schedule: times (UTC and local), height, direction, brightness, rating and when it can be seen by eye, optionally with the first pass's sky chart.
get_positionWhere a satellite, or up to 10 at once, is now or at a given time: the point below it, altitude, whether it is sunlit, and with a place, its azimuth and elevation there; optionally one satellite's ground track over up to a day.
get_pass_weatherCloud-cover forecast and viewing probability for a place and time, or available:false with the reason.
get_pass_chartA rendered polar sky chart (PNG) of a pass, the next one or the one at a given time: where to look, with the moon, planets and stars in place.
get_satelliteWhat a satellite is: owner, launch and re-entry, orbit, size, radio downlinks and its TLE.
search_satellitesFind any satellite in the catalog (about 17,000) by name, alias or NORAD number.
get_radio_passKnown frequencies, Doppler swing, when to tune where and where to point, for one pass (or 24 hours for a satellite that never sets).
find_best_passThe best upcoming pass over a place, for one satellite or from a scan: visual mode scans the popular satellites plus CelesTrak's visual group (the brightest objects) with the cloud forecast folded in; radio mode scans every satellite with known downlinks, optionally by band or mode.
find_satellites_up_nowWhat is in the sky over a place right now, from the whole catalog: brightest in a dark sky, or radio satellites highest first.
identify_satellite"What was that moving light?" The satellites that were sunlit near where and when it was seen, best match first.

What results include

  • Every tool publishes an output schema, and every successful result comes back twice: as JSON text and as structuredContent matching that schema (a chart adds a PNG image block last).
  • Satellite results include url, the satellite's page on seeksat.com, to link to. Pass rows add passUrl, which opens that exact pass from that place.
  • Times are UTC ISO 8601. Results with a place add resolvedLocation.timeZone (IANA) and, next to every time, the same moment on the observer's clock with its offset: rise and riseLocal, peak and peakLocal, and so on.
  • Time inputs: ISO 8601 with Z or an offset, e.g. "2026-11-14T21:00:00-06:00"; a time with no offset, e.g. "2026-11-14T21:00", is read in the observer's time zone, and the result echoes how it was read (interpretedAs). A local time the clocks skip at a daylight-saving change is moved forward, with a note.
  • Pass rows say when the satellite can really be seen: visibleFrom and visibleUntil (null if never on that pass), and leavesShadow or entersShadow when it appears or fades mid-sky. sunlit is only the state at the peak. Azimuths come with compass words (direction) and peakRangeKm is the distance at the peak.
  • Pass rows carry rating, the rating seeksat.com shows: { word, bars (1-5), level, reason, and in visual mode headroomMag, how far it outshines the faintest stars you can see }, from brightness against the sky (skyType) and the cloud forecast in visual mode, and from peak height in radio mode. captureProbability (quality is its old name) is the chance a camera captures the pass, a different number that leaves brightness out.
  • Magnitudes are measured for most of the bright satellites (Mike McCants' Quicksat magnitudes), and a Starlink still in its launch train gets a typical train brightness. For any other satellite the magnitude is a cautious estimate from an assumed small size, marked peakMagnitudeEstimated or magnitudeEstimated, and a visual pass rated on it stops at Fair, as on the site.
  • elementAge grades the orbital elements behind a result as the site does: fresh, old (over 7 days) or stale (over 14), with a warning when not fresh. Whole-sky tools and find_best_pass scans leave stale objects out and count them (skippedStaleElements). A tool for one satellite refuses to work out any time more than 30 days from the elements' epoch, whether now, a time asked about, the end of a search window, or the pass it answers with.
  • An empty pass list comes with a note saying why. get_pass_weather answers available:false with a reason when it has no forecast for the time.
  • Every tool only reads (readOnlyHint). Tools that take a place name are open-world: they geocode it with OpenStreetMap. get_pass_weather, and in visual mode find_best_pass, find_passes and get_pass_chart, fetch a cloud forecast.

Tool parameters

find_passes: Find passes

Upcoming passes of one satellite or several over a location within windowHours (default 48, or 72 with limit; up to 240), in time order and not ranked: limit 1 for "when is the next pass?", no limit for the full schedule ("when does it pass this week?"). Which pass tool: find_passes lists passes in time order, from the next one (limit 1) to every pass in the window; find_best_pass ranks them by rating, for one satellite or, with none named, from a scan of many ("what can I see tonight?"); get_radio_pass gives one pass's Doppler and tuning, the next one by default. chart:true also draws the first pass listed as a sky chart (the image get_pass_chart gives) in this same result, so one call answers when and where to look. For another pass's chart give its peak time to get_pass_chart; to check clouds give it to get_pass_weather.

With a list of up to 10 satellites the result is one combined schedule: each pass also names its satellite, and satellites has one entry per satellite (one that can't be found gets an error there; the others still answer). Duplicates are listed once, and limit counts passes across the whole list. One satellite, not in a list, puts satellite, noradId and url at the top.

mode "visual" (default) keeps only the part of each pass that can be seen by eye, so rise and set can fall mid-sky and the peak is the highest point of that part; mode "radio" keeps the whole pass above minElevation. Rise and set are where it crosses minElevation, not the horizon, so a higher minElevation gives shorter, fewer passes. In visual mode the cloud forecast for the place is folded into the ratings.

rating is the one seeksat.com shows. Visual mode: how much brighter than the faintest visible star for skyType the pass gets (headroomMag), a level lower for some forecast cloud and one bar for a cloudy forecast, up to 4 days ahead; at most Fair when the brightness is estimated or the peak is below 15 degrees, at most Good below 25 degrees or when seen for under 90 seconds, and Excellent only above 40 degrees. Radio mode: the peak height, a bar lower for each 6 dB of extra path loss beyond 2,000 km, and at most Fair when SatNOGS stations tried at least 3 times in 30 days and heard nothing.

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); when the next pass is further off, give a longer windowHours. Each pass is about 1 KB. SeekSat keeps nothing between calls (no saved places, lists or alerts), so give the place every time; for a reminder, give the user passUrl, which opens the pass on seeksat.com, where Remind me alerts them before it starts. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. Cloud forecasts are cached for 10 minutes per area. Over 72 hours (unless limit is 5 or less), with more than one satellite, or with chart:true it is a heavy call: one at a time per caller; another waits up to 20 seconds, then is refused as busy.

ParameterTypeDetails
satellite (required)string or whole number or array of (string or whole number)NORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss"; or a list of up to 10, e.g. [25544, 48274], for one schedule of all their passes.
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
windowHoursnumber, above 0, up to 240how far ahead to look, in hours, up to 240 (10 days). Default 48, or 72 with limit.
minElevationnumber, 0 to 90lowest 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.
mode"visual" | "radio""visual" (default): naked-eye passes, sunlit while the sky is dark; "radio": every line-of-sight pass, day or night.
skyType"city" | "suburban" | "rural" | "dark"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".
limitwhole number, 1 to 100return only the first limit passes in time order, 1 to 100: 1 for the next pass. Default: every pass in the window.
chartbooleantrue to also render the first pass's polar sky chart (PNG, 800 by 897 pixels, about 120 KB) and return it in this same result. Default false.

get_position: Satellite position

Where a satellite is now, or at a given time: the point on Earth straight below it, its altitude, whether it is sunlit, and its page url. For every satellite in the sky right now use find_satellites_up_now; for when it passes over use find_passes; for its orbit and TLE use get_satellite.

With a place (lat and lon, or location) it also gives where the satellite is in that place's sky (azimuth, apparent elevation, range and whether it is above the horizon), and the place sets the time zone for local times and for reading a time with no offset; without one, times are UTC.

With durationMinutes it also gives the ground track from that time on, one point every stepSeconds (up to a day, at most 720 points of about 0.3 KB each), with the sky fields too when a place is given. lonDeg jumps between 180 and -180 at the antimeridian, so split a drawn line there.

With a list of up to 10 satellites ("where are the ISS and Tiangong now?") it gives where each is at that one moment: positions has one entry per satellite with its name, noradId, url and the fields above (one that can't be found or worked out gets an error there; the others still answer), and time, resolvedLocation and interpretedAs stay at the top. Duplicates are listed once. A ground track takes one satellite, not a list.

A time more than 30 days from the orbital elements' epoch is refused. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. With more than one satellite it is a heavy call: one at a time per caller; another waits up to 20 seconds, then is refused as busy.

ParameterTypeDetails
satellite (required)string or whole number or array of (string or whole number)NORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss"; or a list of up to 10, e.g. [25544, 48274], for where each is at the same moment (no ground track with a list).
timestringwhen (with durationMinutes, where the track starts). Default: now. ISO 8601 with Z or an offset, e.g. "2026-11-14T21:00:00-06:00"; a time with no offset, e.g. "2026-11-14T21:00", is read in the observer's time zone, and the result echoes how it was read (interpretedAs). A local time the clocks skip at a daylight-saving change is moved forward, with a note.
durationMinutesnumber, above 0, up to 1440how long a ground track to return, in minutes from time, up to 1440 (a day); about 93 is one ISS orbit. Omit for one position.
stepSecondswhole number, 10 to 3600seconds between track points, 10 to 3600. Default 60, or wider when needed to keep the track to 720 points; a step you give that would make more is refused, naming the smallest that fits.
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap. Optional here: with it, the result adds azimuth and elevation from there.

get_pass_weather: Pass weather

Cloud-cover forecast (Open-Meteo and MET Norway) and the chance of a clear view for a location at one time, such as a pass's peak. The forecast reaches about 7 to 16 days ahead, and viewingProbability is blended toward 0.5 the further ahead the time is, since forecasts lose skill.

It knows nothing about satellites: give the place a pass was found for and that pass's peak time from find_passes or find_best_pass. In visual mode those already fold the forecast into their ratings, so call this to show the cloud numbers or to check another time. With no forecast for that time (in the past, beyond the forecast, a time it cannot read, or a failed fetch), available is false with a reason, never a stand-in number.

Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. Forecasts are cached for 10 minutes per area (rounded to about 11 km), and a fetch gives up after 8 seconds.

ParameterTypeDetails
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
time (required)stringthe time to check, e.g. a pass's peak. ISO 8601 with Z or an offset, e.g. "2026-11-14T21:00:00-06:00"; a time with no offset, e.g. "2026-11-14T21:00", is read in the observer's time zone, and the result echoes how it was read (interpretedAs). A local time the clocks skip at a daylight-saving change is moved forward, with a note.

get_pass_chart: Pass sky chart

Render a polar sky chart of a satellite's pass over a location: where to look, with the moon, planets and stars in place. Returns the charted pass (the same row find_passes gives) and a one-line summary as JSON, then the image, a PNG of 800 by 897 pixels, about 120 KB. By default it charts the next pass; give time (a pass's rise or peak from find_passes or find_best_pass) to chart that pass, with the same minElevation it came from. A geostationary satellite has no passes: stationary says where to point instead, with no image. A time more than 30 days from the orbital elements' epoch is refused. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. A heavy call: one at a time per caller; another waits up to 20 seconds, then is refused as busy.

ParameterTypeDetails
satellite (required)string or whole numberNORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss".
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
timestringcharts the pass around this time (a pass's rise or peak from find_passes or find_best_pass). Default: the next pass from now. ISO 8601 with Z or an offset, e.g. "2026-11-14T21:00:00-06:00"; a time with no offset, e.g. "2026-11-14T21:00", is read in the observer's time zone, and the result echoes how it was read (interpretedAs). A local time the clocks skip at a daylight-saving change is moved forward, with a note.
mode"visual" | "radio""visual" (default): naked-eye passes, sunlit while the sky is dark; "radio": every line-of-sight pass, day or night.
minElevationnumber, 0 to 90lowest 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.
skyType"city" | "suburban" | "rural" | "dark"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".
windowHoursnumber, above 0, up to 240how far ahead to look, in hours, up to 240 (10 days). Default 72. Only used to find the next pass when no time is given.

get_satellite: Satellite details

Facts about one satellite, for "what is this satellite?" or to get its TLE: a plain-words summary, object type, owner, launch and re-entry, orbit, size, radio downlinks and its current orbital elements (TLE lines, or OMM past NORAD 99999) with their age. It takes no location or time: for where it is use get_position, for when to see it use find_passes or find_best_pass, and for a pass's Doppler and reception use get_radio_pass.

Owner, launch and type come from CelesTrak's satellite catalog and are null when it does not say; orbit is null once it has re-entered. Outside the popular list a name resolves only on an exact whole-name match, so prefer NORAD numbers from search_satellites.

Most satellites come from SeekSat's own copy of the catalog, refreshed every four hours; one missing from it is fetched from CelesTrak, which can take a few seconds and is limited per hour. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change.

ParameterTypeDetails
satellite (required)string or whole numberNORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss".

search_satellites: Search satellites

Search the full satellite catalog by name, alias or NORAD number, best match first, to turn a name like "SDO" or "NOAA 19" into a NORAD number for the other tools (they resolve a name outside the popular list only on an exact whole-name match). For the popular satellites use list_satellites; for one satellite's facts and TLE use get_satellite.

Matching order: an exact NORAD number, the whole name, the start of the name or of a word, part of the number, anywhere in the name, then near misses, so a small typo still finds it. To find satellites by downlink kind, use mode "radio" with the kind as the query (query "sstv"). No match is an empty list. Reads only SeekSat's catalog. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change.

ParameterTypeDetails
query (required)stringa name, part of one, or a NORAD number, e.g. "sdo", "noaa 19", "25544". With mode "radio", a downlink kind as the whole query (e.g. "sstv", "aprs", "cw") lists satellites that have one.
limitwhole number, 1 to 20how many results to return, 1 to 20. Default 10.
mode"visual" | "radio""visual" (default): best name match first; "radio": satellites with known radio downlinks first among equally good matches. To list satellites with a kind of downlink, set mode "radio" and put the kind in query (e.g. query "sstv"); mode itself takes only "visual" or "radio".

get_radio_pass: Radio pass details

Radio details for one pass of a satellite over a location: its known downlink (and uplink) frequencies, the Doppler swing, when to tune to what (at 10 and 30 degrees up and at closest approach), and a table of at most 40 evenly spaced rows for pointing an antenna and tuning a radio. To choose a satellite or pass first use find_best_pass with mode radio, or find_passes; for a sky chart of the pass use get_pass_chart.

It uses the first pass that climbs above minElevation within windowHours (default 48), or with time the pass peaking nearest it (past or future, within 30 days of the elements' epoch). If there is none, window is null and message says why; the downlinks are still listed. A satellite that never sets here (geosynchronous) gets the next 24 hours instead. frequencyMHz picks the downlink; by default it is the one SatNOGS stations heard most recently, else the catalog's.

Predictions come from published elements: the transmitter's own offset is unknown, so compare the curve's shape. passUrl opens this pass on seeksat.com on the same frequency, and its Radio chart downloads the full table as CSV. Reception data is from SatNOGS Network (CC BY-SA 4.0). Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none.

ParameterTypeDetails
satellite (required)string or whole numberNORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss". e.g. "so-50" or 27607.
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
frequencyMHznumber, above 0, up to 300000the downlink to compute Doppler for, in MHz. Default: the satellite's default known downlink.
timestringa time near the wanted pass's peak (e.g. from find_passes), past or future. Default: the next pass. ISO 8601 with Z or an offset, e.g. "2026-11-14T21:00:00-06:00"; a time with no offset, e.g. "2026-11-14T21:00", is read in the observer's time zone, and the result echoes how it was read (interpretedAs). A local time the clocks skip at a daylight-saving change is moved forward, with a note.
minElevationnumber, 0 to 90lowest 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.
windowHoursnumber, above 0, up to 240how far ahead to look, in hours, up to 240 (10 days). Default 48. How far past the start to look for a pass.

find_best_pass: Best pass

The best upcoming passes over a location, ranked by the rating seeksat.com shows ("what's the best pass tonight?"): best is the top pass and passes the top limit (default 3, up to 20), each naming its satellite. Which pass tool: find_passes lists passes in time order, from the next one (limit 1) to every pass in the window; find_best_pass ranks them by rating, for one satellite or, with none named, from a scan of many ("what can I see tonight?"); get_radio_pass gives one pass's Doppler and tuning, the next one by default. For what is up at this moment use find_satellites_up_now; to draw the winning pass set chart:true, or give a pass's peak time to get_pass_chart.

What it searches. With satellite: that satellite's passes, the top limit and not every pass. Without, a scan: visual mode (default) covers the popular satellites plus CelesTrak's visual group of the brightest objects, over 72 hours (up to 168); radio mode covers every satellite with known downlinks over 24 hours (up to 72), optionally only those with a downlink in bands or of a kind in modes. A scan leaves out satellites whose elements are more than 14 days old and counts what it skipped.

mode "visual" (default) keeps only the part of each pass that can be seen by eye, so rise and set can fall mid-sky and the peak is the highest point of that part; mode "radio" keeps the whole pass above minElevation. Rise and set are where it crosses minElevation, not the horizon, so a higher minElevation gives shorter, fewer passes.

rating is the one seeksat.com shows. Visual mode: how much brighter than the faintest visible star for skyType the pass gets (headroomMag), a level lower for some forecast cloud and one bar for a cloudy forecast, up to 4 days ahead; at most Fair when the brightness is estimated or the peak is below 15 degrees, at most Good below 25 degrees or when seen for under 90 seconds, and Excellent only above 40 degrees. Radio mode: the peak height, a bar lower for each 6 dB of extra path loss beyond 2,000 km, and at most Fair when SatNOGS stations tried at least 3 times in 30 days and heard nothing.

Ranking. Visual: rating bars, then a measured brightness before an estimated one, then headroomMag, then captureProbability, with the cloud forecast folded in where it reaches. Radio scans: satellites a hobby receiver can tune (30 MHz to 1 GHz) first unless bands is given, then rating bars, then how recently SatNOGS stations heard it (48 hours, 7 days, 30 days, unknown, probably silent), then how often, then peak elevation, then captureProbability. Unknown reception never holds a satellite down. Reception data is from SatNOGS Network (CC BY-SA 4.0).

An empty result comes with a note saying why. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. Cloud forecasts are cached for 10 minutes per area. A heavy call: one at a time per caller; another waits up to 20 seconds, then is refused as busy.

ParameterTypeDetails
satellitestring or whole numberNORAD 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.
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
windowHoursnumber, above 0, up to 240how 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.
minElevationnumber, 0 to 90lowest 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.
limitwhole number, 1 to 20how many ranked passes to return, 1 to 20. Default 3.
mode"visual" | "radio""visual" (default): naked-eye passes, sunlit while the sky is dark; "radio": every line-of-sight pass, day or night.
skyType"city" | "suburban" | "rural" | "dark"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".
bandsarray of "hf" | "wx" | "2m" | "70cm" | "l" | "s" | "other"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.
modesarray of "fm" | "ssb" | "usb" | "lsb" | "cw" | "sstv" | "aprs" | "afsk" | "bpsk" | "gmsk" | "fsk" | "lrpt" | "apt" | "repeater" | "transponder" | "beacon" | "digipeater" | "voice" | "telemetry"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.
chartbooleantrue to also render the winning pass's polar sky chart (PNG, 800 by 897 pixels, about 120 KB) and return it in this same result. Default false.

find_satellites_up_now: Satellites up now

What is in the sky over a location right now, from every satellite in the catalog (active satellites plus CelesTrak's visual group). For upcoming passes use find_best_pass or find_passes; for one satellite at any time, get_position with a place.

mode "visual" (default): sunlit satellites above minElevation while the sky is dark there (the Sun more than about 6 degrees down), brightest first; magnitudes are measured for most bright satellites (McCants' observations) and estimated for the rest. mode "radio": satellites with known downlinks above minElevation, day or night, those a hobby receiver can tune (30 MHz to 1 GHz) first, then the most recently heard by SatNOGS, then the highest.

Up to limit (default 10, up to 50). Satellites whose elements are more than 14 days from now are left out and counted. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. A heavy call: one at a time per caller; another waits up to 20 seconds, then is refused as busy.

ParameterTypeDetails
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
mode"visual" | "radio""visual" (default): sunlit satellites in a dark sky, brightest first; "radio": satellites with known downlinks, day or night: those a hobby receiver can tune first, then the most recently heard, then the highest.
minElevationnumber, 0 to 90lowest elevation to list, in degrees above the horizon (0 to 90). Default 10.
limitwhole number, 1 to 50how many satellites to return, 1 to 50. Default 10.

identify_satellite: Identify a satellite

"What was that moving light?" Given where and when a light was seen, lists the satellites that were sunlit, above the horizon and within tolerance degrees of that spot, best match first, from every satellite in the catalog. For satellites up at this moment use find_satellites_up_now; for upcoming passes use find_passes or find_best_pass.

A match must lie within tolerance of the reported spot (azimuth or direction, plus elevation). travel never adds a match; it only re-ranks them by how well each one's direction of travel agrees. Sightings by eye are often 10 to 20 degrees off, so widen tolerance before concluding nothing matched.

It needs the Sun at least about 3 degrees below the horizon: if the sky was too bright, a note says so instead of a list, and with no match a note suggests checking the time and direction or widening tolerance. Satellites whose elements are more than 14 days from the sighting are left out and counted. Read-only, free, no key needed; up to 120 requests per 60 seconds per IP address. A bad input or a failure comes back as an error result (isError) whose text names the problem and what to change. A place name is looked up with OpenStreetMap (one lookup a second, cached), which can add a few seconds; lat and lon or a grid square need none. A heavy call: one at a time per caller; another waits up to 20 seconds, then is refused as busy.

ParameterTypeDetails
latnumber, -90 to 90observer latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonnumber, -180 to 180observer longitude in decimal degrees, east positive and west negative (-180 to 180).
locationstringwhere 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), read locally, or a place name (city, address, landmark) looked up with OpenStreetMap.
timestringtime of the sighting. Default: now. ISO 8601 with Z or an offset, e.g. "2026-11-14T21:00:00-06:00"; a time with no offset, e.g. "2026-11-14T21:00", is read in the observer's time zone, and the result echoes how it was read (interpretedAs). A local time the clocks skip at a daylight-saving change is moved forward, with a note.
azimuthnumber, 0 to 360where it was, in degrees from north (90 = east), 0 to 360. Give this or direction.
directionstringwhere it was, as a compass word: N, NNE, NE,... or "north-east".
elevation (required)number, 0 to 90how high it was, in degrees above the horizon (0 to 90, 90 = straight up). Required.
travelstringthe compass direction it was moving towards, e.g. "NE". Optional, but it sharpens the match.
tolerancenumber, 1 to 45how far off the reported spot a match may be, in degrees, 1 to 45. Default 10.
limitwhole number, 1 to 10how many candidates to return, 1 to 10. Default 5.

Design decisions

  • Deterministic core. Pass geometry, magnitude, visibility and the observer's time zone are worked out on the server with no outside calls. Only three things reach other services: geocoding a place name (OpenStreetMap), the cloud forecast (Open-Meteo and MET Norway, for get_pass_weather and visual find_best_pass), and fetching a satellite missing from the catalog snapshot (CelesTrak).
  • Cron-cached, epoch-guarded TLEs. A 4-hour cron mirrors the CelesTrak catalog into Vercel Blob; requests read from that snapshot, with a rate-limited CelesTrak lookup only for satellites not in it. A flaky source returning an older element set can't clobber good data, and an upstream outage just means serving the last-known-good TLE, still SGP4-valid for days.
  • Whole-catalog questions stay fast. find_satellites_up_now and identify_satellite take one orbit step per satellite at one moment. The find_best_pass scans sweep their candidates for rough passes (elevation only, skipping time a satellite cannot rise; for visual passes also sunlight and a dark sky), cache that per area and hour, and run the full engine only on the best candidates.
  • Measured brightness where known. Magnitudes use Mike McCants' Quicksat intrinsic magnitudes (mmccants.org) for most of the bright satellites, measured by satellite observers; a Starlink still flying in its launch train gets a typical train brightness. Anything else is assumed small and faint, flagged peakMagnitudeEstimated / magnitudeEstimated, and rated no higher than Fair.
  • Engine reuse. Every pass number comes from the same unit-tested lib/pass-finder/* modules that drive the web app, so the two faces can't drift.