Satellite measurements

weather.satellite() extracts native Level 2 measurements at a station or arbitrary coordinates. Every row identifies the instrument family, scan time, product, variable, units, quality status, and source object.

Install the Python extra

pip install "mostlyrightmd-weather[satellite]"

Satellite decoding uses optional array, object-store, and HDF5 dependencies. The module remains importable without them, but a fetch raises SourceUnavailableError with the install command.

Fetch one station

from datetime import UTC, datetime
from mostlyright import weather

pixels = weather.satellite(
    "KNYC",
    satellite="goes16",
    product="ABI-L2-ACMC",
    from_time=datetime(2024, 6, 15, tzinfo=UTC),
    to_time=datetime(2024, 6, 15, 23, 59, tzinfo=UTC),
)

print(pixels[[
    "station",
    "satellite",
    "product",
    "variable",
    "scan_start_utc",
    "pixel_value",
    "units",
    "source",
    "qc_status",
]])

The result contains one row per station, variable, and scan. Satellite measurements are model inputs. They never replace an official weather-market settlement value.

Let the SDK choose the instrument

Omit satellite= to choose an available instrument family from the first station’s location:

pixels = weather.satellite(
    "RJTT",
    from_time=datetime(2024, 6, 15, tzinfo=UTC),
    to_time=datetime(2024, 6, 15, 23, 59, tzinfo=UTC),
)

GOES covers the Americas and eastern Pacific. Himawari covers Asia-Pacific. VIIRS supplies polar coverage. Europe, Africa, and the Indian Ocean route to Meteosat. That route requires EUMETSAT Data Store credentials and raises MeteosatCredentialsRequiredError when they are missing. Pass satellite="viirs-n20" explicitly to keep using VIIRS in that region.

For a station list that crosses coverage regions, split the request by region or name the instrument explicitly. One auto-routed instrument is applied to the whole call.

Fetch arbitrary coordinates

Pass lat and lon instead of a station code:

pixels = weather.satellite(
    lat=40.7789,
    lon=-73.9692,
    from_time=datetime(2024, 6, 15, tzinfo=UTC),
    to_time=datetime(2024, 6, 15, 23, 59, tzinfo=UTC),
)

The SDK derives a legible site id at 0.01° precision. This example uses N4078W07397 as the row’s station and as the cache partition. Use site_id= or tz_override= only when you need to override the derived identity or timezone.

Pass exactly one identity form: either station, or both lat and lon. Conflicting or incomplete identity arguments raise ContractError before a network request. Station lookup now uses the full packaged catalog of 6,419 stations, not only the settlement-station list.

Source identity

| Row source | Instrument family | | --- | --- | | noaa_goes | GOES-East and GOES-West ABI | | jma_himawari | Himawari AHI | | noaa_viirs | VIIRS polar swath | | eumetsat_meteosat | Meteosat SEVIRI |

Transport does not change source identity. AWS and GCP mirrors of the same NOAA product still return source="noaa_goes".

Time and quality fields

scan_start_utc and scan_end_utc describe the source scan.
knowledge_time or as_of_time records when the row became available when that timestamp exists.
qc_status is clean, flagged, or suspect; rows are annotated rather than silently dropped.
source_object_key, pixel coordinates, and station coordinates keep the extracted value traceable to its source file.

Use an aware UTC as_of= timestamp when you need to filter rows by availability time. A naive datetime is rejected.

TypeScript hosted delivery

TypeScript exposes the credentialed hosted consumer:

import { satelliteHosted } from "@mostlyrightmd/weather/hosted";

const rows = await satelliteHosted({
  hostedUrl,
  apiKey,
  lat: 40.7789,
  lon: -73.9692,
  satellite: "goes16",
  product: "ABI-L2-ACMC",
  fromTime: "2024-06-15T00:00:00Z",
  toTime: "2024-06-15T23:59:00Z",
});

The hosted method requires the service URL, API key, exactly one identity form, an explicit satellite, and a time window before it makes a request. Coordinate requests derive the same site id in TypeScript as in Python. Do not put a durable shared API key in a public browser bundle.