satmarg 0.3.2

Predict satellite overpasses based on TLE and user location

SatMarg - Satellite Overpass Predictor

SatMarg = Satellite + Marg (Sanskrit for "path" or "orbit")
Predict satellite overpass times for any location easily and precisely.

About SatMarg

SatMarg is an open source Python package designed to calculate satellite overpass predictions for specific locations and time periods. It uses real-time Two-Line Element (TLE) data to provide precise estimates of when satellites such as SENTINEL-2A, SENTINEL-2B, LANDSAT 8, and others will pass closest to a given latitude and longitude. SatMarg is built to be fast, simple, and customizable, allowing users to adjust processing speed and proximity angle according to their needs. It is ideal for applications such as satellite image planning, ground station scheduling, and general orbital analysis.

Features

• Fetches real-time TLE data automatically from Celestrak.
• Predicts precise satellite overpass dates and times for a given latitude and longitude.
• Supports Sentinel-2A, Sentinel-2B, Sentinel-2C, Landsat 8/9, ISS, and more with TLE data available on Celestrak https://celestrak.org/NORAD/elements/resource.txt, https://celestrak.org/NORAD/elements/stations.txt
• Allows control of processing speed (slow, medium, fast) to balance between precision and performance.
• Allows customization of proximity angle detection (default is 0.5 degrees).
• Lightweight, fast, and easy to use.

Installation

pip install satmarg

Usage

from satmarg.core import get_precise_overpasses

# Basic usage
df = get_precise_overpasses(
    lat=27.7172,   # Kathmandu
    lon=85.3240
)
print(df)

# Advanced usage
df = get_precise_overpasses(
    lat=27.7172,
    lon=85.3240,
    start_date="2025-04-26", 
    end_date="2025-05-27", 
    timezone="Asia/Kathmandu",  #default: "UTC"
    satellites="SENTINEL-2A, SENTINEL-2B, SENTINEL-3A, LANDSAT 8", 
    max_angle_deg="0.7", # one angle for all satellite or custom angles for each eg. "0.7, 0.7, 0.5, 0.7",
    step_seconds=10,   # custom processing speed, default is 1. 
    output_format='json', 
)
print(df)

Parameters

Parameter	Description	Default
lat	Latitude in degrees.	Required
lon	Longitude in degrees.	Required
start_date	Start date in 'YYYY-MM-DD' format. Timezone is specified on the parameter below. If not specified, default: UTC	Today
end_date	End date in 'YYYY-MM-DD' format. Timezone is specified on the parameter below. default: UTC	30 days later
timezone	Optional timezone for local time conversion in IANA format (e.g., "Europe/Vienna"). If invalid, defaults to UTC with a warning. Local Time column is included in output only if timezone ≠ UTC. Check Supported Timezones section below.	"UTC"
satellites	Comma-separated list of satellites (example: "SENTINEL-2A, SENTINEL-2B") - limit 7 satellites. Check supported satellites section below.	SENTINEL-2A, SENTINEL-2B
max_angle_deg	Maximum distance (in degrees) from overhead to detect an overpass.	"0.7" or comma separated values for each satellite (example: "0.5, 0.7, 0.6")
step_seconds	Step interval for orbit simulation in seconds. Higher = faster but less precise.	1
output_format	Format of the returned overpass results. Options: "json" (default, returns JSON string), "table" (pandas DataFrame), or "csv" (saves results to CSV).	"json"

Notes:

• step_seconds = 1 for slow (high precision) and requires more processing power reduce it to lower values if it is taking too long,
• step_seconds = 2 for medium,
• step_seconds = 5 for fast (less precision). Or it can be custom steps like 3 or 7
• Timezone: When timezone is set, all the input and output dates are in user-defined time zone. "

Output

You can control the output format using the output_format parameter. Available options are:

'json' (default): Returns the overpass results as a JSON string.

'table': Returns the results as a pandas DataFrame.

'csv': Saves the results directly to a CSV file (you can also specify a csv_filename).

Example Output (json)

json [
  {
    "Date":"2026-01-02T22:16:24+05:45",
    "Timezone":"Asia\/Kathmandu",
    "Satellite":"SENTINEL-2B",
    "Lat (DEG)":27.6861089603,
    "Lon (DEG)":85.1511018967,
    "Sat. Azi. (deg)":263.7250417017,
    "Sat. Elev. (deg)":88.7969902437,
    "Range (km)":791.8631112307
  },
  {
    "Date":"2026-01-12T22:16:27+05:45",
    "Timezone":"Asia\/Kathmandu",
    "Satellite":"SENTINEL-2B",
    "Lat (DEG)":27.6401258516,
    "Lon (DEG)":85.1484809155,
    "Sat. Azi. (deg)":245.8365823306,
    "Sat. Elev. (deg)":88.665605964,
    "Range (km)":791.7747502366
  }
]

Example Output (Table)

Date	Timezone	Satellite	Lat (DEG)	Lon (DEG)	Sat. Azi. (deg)	Sat. Elev. (deg)	Range (km)
2026-01-02T22:16:24+05:45	Asia/Kathmandu	SENTINEL-2B	27.686109	85.151102	263.725042	88.796990	791.863111

Supported Satellites

• LANDSAT 8
• LANDSAT 9
• SENTINEL-2A
• SENTINEL-2B
• SENTINEL-2C
• SENTINEL-3A
• SENTINEL-3B
• ISS (ZARYA)
• and more available on https://celestrak.org/NORAD/elements/resource.txt, https://celestrak.org/NORAD/elements/stations.txt

Supported Timezones

• These are the valid timezones: https://raw.githubusercontent.com/geomatupen/satmarg/refs/heads/upen/Example/valid_timezones/valid_timezones.csv

License

GNU GENERAL PUBLIC LICENSE

Acknowledgements

• Skyfield: Precise astronomical computation library.
• Celestrak: Satellite TLE data provider.
• Special thanks to Termatics, Austria for providing the opportunity and support to develop this project.