---
title: "Next satellite passes over a target"
method: GET
path: "/api/v1/passes"
---

# Next satellite passes over a target

`GET /api/v1/passes`

## Request

- Base URL: `https://offnadir-delta.com`
- URL: `https://offnadir-delta.com/api/v1/passes`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Costs 2 token(s) per request. Propagates current orbital elements (SGP4 over day-cached CelesTrak two-line elements) and returns the access windows over a point for 13 families: Sentinel-1 (SAR), Sentinel-2, Landsat and NISAR are free and SYSTEMATIC (routinely collecting sensors — each pass is still a geometric opportunity, not a scheduled acquisition; units whose operator announced the end of operations are excluded); WorldView, ICEYE, Capella, SkySat, Umbra, Synspective, iQPS, RADARSAT-2 and COSMO-SkyMed are commercial and AGILE (taskable ACCESS opportunities that require a paid order — NOT guaranteed collects). Each pass carries acquisition/loss and closest-approach times, peak elevation, off-nadir angle, ground distance, ascending/descending, solar elevation and sunlit flag, plus the age of the element set used. Give lat and lon, or a bbox whose centre is used. The window is capped to a 7-day horizon. When orbital elements cannot be retrieved the response sets retrieval_ok:false — that means timing is UNAVAILABLE, never "no passes". Orbital data by CelesTrak.

## Query parameters

- `lat` number
- `lon` number
- `bbox` string
- `start_date` string, date
- `end_date` string, date
- `satellites` string
- `max_passes` integer

## Response `200`

Access windows over the target, soonest first.

- object
  - `meta` object
  - `passes` object[]
    - `satellite` string
    - `family_key` string
    - `sensor` 'optical' | 'sar'
    - `collection_mode` 'systematic' | 'agile': systematic = a routinely collecting sensor (a geometric opportunity, not a scheduled acquisition); agile = a taskable access opportunity requiring a paid order.
    - `start` string, date-time
    - `peak` string, date-time: Closest approach — the collection instant.
    - `end` string, date-time
    - `duration_min` number
    - `peak_elevation_deg` number
    - `off_nadir_deg` number: 0 = overhead. Large angles degrade resolution and geometry.
    - `ground_distance_km` number
    - `direction` 'ascending' | 'descending'
    - `solar_elevation_deg` number: At the target, at peak. Below 0 = night.
    - `sunlit` boolean: Optical needs light; SAR does not.
    - `access` 'in_swath' | 'in_off_nadir_cone'
    - `tle_epoch` string, date-time
    - `tle_age_days` number: Days between the element-set epoch and THIS pass. Signed: negative means the pass precedes the epoch (a hindcast), not that the elements are from the future.
    - `is_past` boolean: The pass has already happened.
  - `freshness` object
    - `max_tle_age_days` number: Largest |tle_age_days| over the returned passes.
    - `stale` boolean: Elements older than 7 days — predicted timing may drift by minutes.
  - `retrieval_ok` boolean: false = orbital elements could not be retrieved; timing is unavailable, NOT "no passes".
  - `total_passes` integer
  - `by_family` object
  - `note` string
  - `attribution` string: Mandatory CelesTrak credit.

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `402` (unresolved $ref)
- `429` (unresolved $ref)

---

[API](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api.md) · [All operations](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api/revisions/5cf3f2bed5a2?raw)