# ISS and Satellite Pass Predictions for Any Location (`arjs1000/satellite-passes-overhead`) Actor

When will the ISS, Tiangong, Hubble or any tracked satellite pass over a place, and will the sky be clear enough to see it? Rise, peak and set times, compass directions, naked-eye visibility and a cloud and fog forecast per pass, for up to 1,000 locations a run.

- **URL**: https://apify.com/arjs1000/satellite-passes-overhead.md
- **Developed by:** [Arjun Shankar](https://apify.com/arjs1000) (community)
- **Categories:** Developer tools, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ISS and Satellite Pass Predictions for Any Location

When will the ISS, Tiangong, Hubble or any tracked satellite pass over a place, where in the sky
should you look, and will the clouds let you see it?

Send one location or a thousand. For each, you get every pass in the window with rise, peak and
set times, compass directions, peak elevation and visibility, plus the forecast cloud cover,
visibility and fog at the moment it peaks. Or ask for a live list of everything overhead right
now. You pay per location, not per pass.

Run it with the default input: the next 24 hours of ISS passes over London.

### Who uses it

- **Agent and chatbot builders** answer "is the ISS going over tonight?" with one tool call.
- **App and smart-home developers** send an alert, or flash a light, ten minutes before a
  visible pass at each user's own location.
- **Teachers and astronomy clubs** plan an evening's viewing: what crosses the sky after dusk,
  where to look and how high it climbs.

### Input

| Field | What it does |
|---|---|
| `mode` | `passes` (default) or `overhead` (what is above the horizon now) |
| `locations` | A list of `{"lat", "lon", "alt_m", "label"}`, up to 1,000 per run |
| `filter` | Empty means the ISS. Or `brightest`, `norad:25544,48274`, or a group such as `group:stations` or `group:oneweb` |
| `hours` | How far ahead to look, 1 to 72. Default 24 |
| `minElevation` | Ignore passes lower than this, in degrees. Default 10 |
| `visibleOnly` | `true` returns only passes where the satellite is lit against a dark sky |
| `includeWeather` | Sky forecast for each pass. Default `true`; reaches about 16 days ahead |
| `start` | Start the window, or set the moment for `overhead`, as ISO 8601 |
| `radiusDeg` | For `overhead`: 90 is the whole sky, 30 is near straight up |

### Output

Each pass carries `name`, `norad_id`, `rise_time`, `peak_time`, `set_time` (UTC, to the
second), `rise_compass`, `peak_compass`, `set_compass`, `peak_elevation`, `duration_s`,
`visible`, `visible_from`, `visible_to`, `magnitude` (ISS, Tiangong and Hubble) and
`data_as_of`.

The sky at the peak comes in `sky`: `verdict` (`clear`, `partly_cloudy`, `poor` or `fog`), a
one-line `reason`, cloud cover for the low, mid and high layers, `visibility_m`, `fog` and
`precipitation_probability_pct`. `naked_eye_viewable` puts it together: the satellite is lit,
your sky is dark and the clouds should allow it. Past the forecast range, `sky` is null and
`sky_note` says why.

A real visible pass of Tiangong over London, trimmed. Bright enough, but the forecast says stay in:

```json
{
  "location_label": "London",
  "name": "CSS (TIANHE-1)",
  "norad_id": 48274,
  "rise_time": "2026-10-09T04:18:58.000Z",
  "rise_compass": "SW",
  "peak_time": "2026-10-09T04:20:41.000Z",
  "peak_compass": "S",
  "peak_elevation": 13.9,
  "set_time": "2026-10-09T04:22:26.000Z",
  "set_compass": "SSE",
  "duration_s": 208,
  "visible": true,
  "magnitude": 0.6,
  "naked_eye_viewable": false,
  "sky": {
    "verdict": "poor",
    "reason": "Mostly cloudy (low 97%, mid 1%, high 66%)",
    "cloud_cover_low_pct": 97,
    "cloud_cover_mid_pct": 1,
    "cloud_cover_high_pct": 66,
    "visibility_m": 19143,
    "fog": false,
    "precipitation_probability_pct": 40
  }
}
```

`overhead` rows give each object's compass direction, elevation, range and height, highest
first.

### Pricing

Pay per location queried. See the Pricing tab for current rates; the number of `locations` sets the cost. A location with no passes charges nothing.

### FAQ

**How current is the orbital data?** Predictions use the latest orbital elements we hold, and
every row carries their age in `data_age_hours`.

**Can I do Starlink?** Yes, in `overhead` mode, or by listing catalogue numbers in `passes` mode
(up to 200 per location).

**What does "visible" mean?** The satellite is in sunlight while your sky is dark enough to see
it. `naked_eye_viewable` adds the weather: it is true only when the forecast for that minute is
clear or partly cloudy.

**How far ahead is the sky forecast?** About 16 days. Passes further out, or in the past, carry
`sky: null` with a `sky_note`. Set `includeWeather` to `false` to leave it out.

Every row carries an `attribution` field; keep it if you republish. Runs record anonymous usage
counts only, never your inputs or results.

# Actor input Schema

## `mode` (type: `string`):

passes: upcoming passes over each location. overhead: objects above the horizon at one moment.

## `locations` (type: `array`):

One object per location: {"lat": 51.5074, "lon": -0.1278, "alt_m": 0, "label": "London"}. lat -90 to 90, lon -180 to 180, alt_m -500 to 9000 (optional, default 0). Up to 1,000 locations. Each location with at least one result is one charged event; a location with nothing in the window is free. Empty = London.

## `filter` (type: `string`):

Leave empty for the default: passes mode returns ISS passes, overhead mode scans the whole catalogue (a wide scan). Otherwise: iss, brightest (ISS, Tiangong, Hubble and the other crewed-station objects), norad:<id>\[,<id>...], or group:<name> (stations, gps-ops, or a constellation such as group:oneweb). Up to 30 objects is a location query; 31-200 is a wide scan (passes mode allows at most 200).

## `hours` (type: `integer`):

Passes mode: how far ahead to look (1-72).

## `minElevation` (type: `integer`):

Passes start and end when the satellite crosses this elevation. 10 is a practical horizon for most sites.

## `visibleOnly` (type: `boolean`):

Only passes where the satellite is sunlit while your sky is dark (Sun below -6 degrees).

## `includeWeather` (type: `boolean`):

Passes mode: add the forecast cloud cover (low, mid and high layers), visibility, fog and precipitation at each pass's peak, with a clear / partly cloudy / poor / fog verdict and whether the pass is worth stepping outside for (naked_eye_viewable). Forecasts reach about 16 days ahead.

## `start` (type: `string`):

ISO 8601 date-time with a zone, between 1957 and 2100, e.g. 2026-10-07T18:00:00Z. Passes mode: the window starts here. Overhead mode: the moment to look. Leave empty for now.

## `radiusDeg` (type: `integer`):

Overhead mode: 90 means the whole sky above the horizon, 30 means within 30 degrees of straight up.

## Actor input object example

```json
{
  "mode": "passes",
  "locations": [
    {
      "lat": 51.5074,
      "lon": -0.1278,
      "alt_m": 0,
      "label": "London"
    }
  ],
  "hours": 24,
  "minElevation": 10,
  "visibleOnly": false,
  "includeWeather": true,
  "radiusDeg": 90
}
```

# Actor output Schema

## `passes` (type: `string`):

Every pass over each location: rise, peak and set times, brightness, sky forecast and whether it is naked-eye viewable.

## `overhead` (type: `string`):

Satellites above each location right now, with direction and elevation.

## `summary` (type: `string`):

What this run returned: mode, item count, data freshness and the cursor for your next run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        {
            "lat": 51.5074,
            "lon": -0.1278,
            "alt_m": 0,
            "label": "London"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("arjs1000/satellite-passes-overhead").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "locations": [{
            "lat": 51.5074,
            "lon": -0.1278,
            "alt_m": 0,
            "label": "London",
        }] }

# Run the Actor and wait for it to finish
run = client.actor("arjs1000/satellite-passes-overhead").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    {
      "lat": 51.5074,
      "lon": -0.1278,
      "alt_m": 0,
      "label": "London"
    }
  ]
}' |
apify call arjs1000/satellite-passes-overhead --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,arjs1000/satellite-passes-overhead"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kjP97U5IZxTcHqzsn/builds/Gns4flsEc41W5sPiG/openapi.json