predict_satellite_passes
Predict when satellites can next image any location. Returns pass times, off-nadir angles, and sunlit conditions for free and taskable commercial sensors to plan collection.
Instructions
WHEN can this place next be imaged, and by WHAT — the timing half of collection planning. Propagates current orbital elements (SGP4 over day-cached CelesTrak two-line elements) for seven families and returns the access windows over a target: Sentinel-1 (SAR), Sentinel-2 and Landsat (free, SYSTEMATIC — routinely collected, so near-certain), plus WorldView, ICEYE, Capella and SkySat (commercial, AGILE — taskable ACCESS opportunities that require a paid order and are NOT guaranteed collects). Each pass carries acquisition/loss times, the closest-approach instant, peak elevation, OFF-NADIR angle, ground distance, ascending/descending, solar elevation and whether the target is sunlit (optical needs light; SAR does not), and the age of the element set it was computed from. Use it to answer "when is the next chance to see this", to choose between waiting for a free systematic pass and paying to task an agile one, and to time a pre/post change-detection pair. Give lat/lon, or a bbox whose centre is used. Horizon is capped at 7 days. If elements cannot be retrieved the result says so (retrieval_ok:false) — that means timing is UNAVAILABLE, never "no passes". Every pass is a GEOMETRIC access opportunity computed from orbital elements and swath width (geometry_only:true, acquisition_plan_verified:false): no operator collection plan is consulted, so this is when a sensor COULD see the target, never a confirmed acquisition schedule. With no start_date the window begins NOW, so the first pass listed is always still ahead. Costs 2 token(s) per call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Target latitude (-90..90; positive = North). Required unless bbox is given. | |
| lon | No | Target longitude (-180..180; positive = East). Required unless bbox is given. | |
| bbox | No | Area [west, south, east, north] in WGS84. The CENTRE is used as the target when lat/lon are omitted. | |
| end_date | No | Inclusive end date YYYY-MM-DD (UTC). Defaults to start+2 days; the window is capped to a 7-day horizon. | |
| max_passes | No | Maximum passes to return, soonest first (default 40). | |
| satellites | No | Families to consider. Omit for all seven. Use this to compare "free systematic only" against "what could I task". | |
| start_date | No | Inclusive start date YYYY-MM-DD (UTC). Defaults to today. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta | Yes | Query echo, token charge/balance (meta.tokens), and pagination where applicable. | |
| passes | Yes | ||
| summary | No | One-line natural-language summary of the result, ready to relay to a user. | |
| freshness | No |