Skip to main content

Weather attenuation

Value
model_familyweather-attenuation
Versionv1
PredictsTotal attenuation in dB, its rain, gas, cloud and scintillation terms, and the rain along the signal's path
TimeOne future instant per request
EntityGround station, satellite, or the pair
ReadsYour network config, radar, rain nowcasts and weather-model forecasts. No telemetry.

Overview​

Predicts how much the atmosphere will weaken the signal between a ground station antenna and a satellite radio at one future instant. Each result gives the total attenuation in dB, the four terms that make it up, and the rain the signal crosses below the rain height. The model follows ITU-R P.618-13. The rain comes from the latest radar scan for the next few minutes, a radar nowcast to 3 hours, then weather-model forecasts to 72 hours.

You name a ground station, a satellite, or both, and a future time. The API reads the antennas, radios and positions from your network config, works out which antennas can see the satellite at that time on a matching band, and returns one item per antenna and satellite through GET /predictions with model_family=weather-attenuation.

One request prices at most 25 antenna and satellite pairs. When more are in view, the API prices the 25 with the satellite highest above the station's horizon at at, closest to overhead. It returns the rest in entity_errors with code prediction_unavailable. Name both a ground station and a satellite to narrow the request.

Intended use​

  • Planning around weather. Find which of your stations will lose the least to rain on an upcoming pass, or how much margin a link will lose at a given time.
  • Recommended prediction horizon. Test it from now to 72 h ahead. Further out, rain is the site's typical figure rather than a forecast.

Inputs​

A request carries these parameters:

ParameterDescription
ground_station_idA ground station in your network config. The API works out which of its antennas to price.
satellite_idA satellite in your network config.
atThe future instant to predict for, in UTC.

Name ground_station_id, satellite_id, or both. See Request predictions.

The model needs no telemetry. It reads the station, its antennas, the satellite and its radios from your network config, which you manage with PUT and PATCH /topology/config. The station's latitude_deg and longitude_deg and the satellite's norad_id or tle are required there. The satellite's orbit comes from its current element set in our orbit catalog, or from its tle. When the station has no altitude_m, the model uses the terrain height from ITU-R P.1511.

The API pairs an antenna with the satellite when one of the satellite's radios has a frequency_ghz inside one of the antenna's frequency_ranges of the same direction, the same links your network config derives. An antenna with no frequency_ranges pairs with any radio. A radio and an antenna whose band letters disagree never pair. When several of the satellite's radios match one antenna, the model prices the one with the highest frequency, the link that can carry the most.

Defaults by band​

Any other field you leave out takes a default for the link's band. The defaults assume the most common setup in that band: the frequency in the middle of the band, and the antenna a commercial ground station network uses most. At 4 GHz and above, efficiency is 0.5 in every band, the value ITU-R P.618 gives when the efficiency is unknown. Below 4 GHz the model reports no scintillation, so it uses neither the diameter nor the efficiency. When a band has no polarization default the model uses a 45° tilt, and when it has no minimum elevation it uses ITU-R P.618's 5° floor. Each item lists in assumptions every default it used.

The model finds the band from the radio's frequency_ghz. A radio without one takes its band from the band letter on the radio or the antenna, or else from the antenna's highest frequency range, and uses that band's default frequency. With neither, the model declines the pair as missing_frequency.

Band edges take the widest range across IEEE 521 and ITU-R V.431 Table 4. V.431 notes that letter bands have no standard mapping to frequencies, and that space systems often call K and Ka together "Ka".

FieldDefaultSource
Frequency16.5 MHz, the middle of 3 to 30 MHzIEEE 521 and ITU-R V.431 Table 1
Antenna diameterNot needed: scintillation is 0 dB below 4 GHz.
Antenna efficiencyNot needed: scintillation is 0 dB below 4 GHz.
Polarization45° tiltITU-R P.838
Minimum elevation5°, ITU-R P.618's floorITU-R P.618

This default is below 1 GHz. The model holds rain and gas at their 1 GHz values there, because the ITU-R formulas break down below it. See Limitations.

Outputs​

One item per ground station antenna and satellite:

FieldUnitDescription
attenuation_dbdBTotal attenuation.
attenuation_rain_dbdBRain term.
attenuation_gas_dbdBOxygen and water vapour term.
attenuation_cloud_dbdBCloud term.
attenuation_scintillation_dbdBScintillation term.
rain_path_mm_h_kmmm/h·kmRain rate integrated along the slant path below the rain height.
rain_path_dbzdBZReflectivity of the path's mean rain rate. −32 for a dry path.
rain_rate_mm_hrmm/hRain rate at the station.
rain_sourceobserved, nowcast, nwp or climatology. See Where the rain comes from.
rain_methodpath_integral when the model traced the path across the radar grid, point otherwise.
elevation_deg, azimuth_deg, slant_range_kmdeg, deg, kmWhere the satellite is, seen from the station.
p_percent% of a yearThe exceedance percentage the climatology terms are priced at. On a climatology rain sample it is the drawn exceedance, so the rain value is a random draw.
nwp_sourceThe weather model run that priced the gas, cloud and scintillation terms, such as hrrr-conus or gfs-0p25. Empty when no run covered the station.
gas_source, cloud_source, scintillation_sourceWhere each term came from: the nwp_source run, or climatology. Null when the source is unknown.
Value
Identityground_station_id, satellite_id, target_at, the time the item is for, and ground_antenna_id, the antenna the API chose at that station.
Provenancemodel_release_id, network_config_version, and the rain data used: rain_dataset, rain_data_at, rain_run_at, rain_lead_min. Keep them with exported results.
assumptionsOne entry per input the model filled with a default: field, the input the default filled (altitude_m, frequency_ghz, antenna_diameter_m, antenna_efficiency, polarization_tilt_deg or min_elevation_deg), the value used, and its basis.
{
"model_family": "weather-attenuation",
"captured_at": "2026-10-26T18:02:45Z",
"items": [
{
"ground_station_id": "gs-den",
"ground_antenna_id": "den-ant-1",
"satellite_id": "sat-goes16",
"target_at": "2026-10-26T18:20:00Z",
"predicted_at": "2026-10-26T18:02:41Z",
"model_release_id": "weather-attenuation/20261024.005635+gd3eba44",
"network_config_version": 7,
"value": {
"attenuation_db": 3.42,
"attenuation_rain_db": 2.91,
"attenuation_gas_db": 0.31,
"attenuation_cloud_db": 0.14,
"attenuation_scintillation_db": 0.06,
"rain_path_mm_h_km": 9.8,
"rain_path_dbz": 31.6,
"rain_rate_mm_hr": 4.7,
"rain_source": "nowcast",
"rain_method": "path_integral",
"rain_dataset": "mrms-conus",
"rain_data_at": "2026-10-26T18:20:00Z",
"rain_run_at": "2026-10-26T18:02:00Z",
"rain_lead_min": 18.0,
"p_percent": 0.01,
"nwp_source": "hrrr-conus",
"gas_source": "hrrr-conus",
"cloud_source": "hrrr-conus",
"scintillation_source": "hrrr-conus",
"elevation_deg": 41.2,
"azimuth_deg": 171.8,
"slant_range_km": 37190.4
},
"assumptions": [
{ "field": "antenna_efficiency", "value": 0.5, "basis": "Ka band default" }
]
}
],
"entity_errors": []
}

Identifiers and values are illustrative.

Request forecasts​

Each request names one future time in at, and one ground station, one satellite, or both:

You nameYou get
ground_station_id and atEvery satellite in your network config that one of the station's antennas can see at at, on a matching band, one item per antenna.
satellite_id and atEvery ground station antenna in your network config that can see the satellite at at, on a matching band.
Both, and atEach antenna and the satellite on a matching band, or a decline that says why there is none.
curl --fail-with-body -sS \
-H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/predictions?model_family=weather-attenuation&ground_station_id=gs-den&satellite_id=sat-goes16&at=$(date -u -v+1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)"

at is one instant in UTC, later than the time the API receives the request. A request with an at in the past is rejected with 400 and code at_not_in_future. To cover a pass, send one request per time you need.

Where the rain comes from​

The rain term's source depends on how far ahead of the request at is. Where radar covers the station (the contiguous US and Europe):

  1. From now to about 20 minutes ahead in the US, about 15 minutes in Europe: observedLatest radar scan at the station
  2. From there to 3 hours after the request: nowcastRain forecast run from recent radar scans
  3. From 3 hours to 72 hours after the newest model run: nwpWeather model rain (HRRR to 18 h in the US, GFS to 72 h)
  4. Past 72 hours, or where no model run covers the time: climatologyA draw from the site's long-term rain distribution (ITU-R P.837), fixed per link for an hour

Outside radar coverage the first two stages do not apply, and the weather model prices the rain from the start. Where a model run covers the time, the gas, cloud and scintillation terms use its state too; elsewhere they come from long-term statistics for the location.

Past the weather model's leads, the rain term is a draw from the site's rain distribution (ITU-R P.837), fixed for each link an hour at a time. It says how often rain of that size occurs there, not whether it will fall on that pass. Most draws are dry.

The boundaries move with each radar scan, nowcast run and model run, so an at near one can come back with either source. rain_source and rain_lead_min on each item tell you which one you got.

From an AI agent, call get_predictions on the MCP server with the same parameters. Both need a key with predictions:read; a test key is refused with 400 sandbox_model_family_unsupported.

Declines​

The API declines a pair, a station or a satellite for:

ReasonCause
not_in_network_configThe ground station or satellite is not in your latest network config, the station you named has no antennas, or the satellite has neither a norad_id nor a tle.
no_visible_pairYou named only a ground station or only a satellite, and no antenna and satellite on a common band are in view at at.
below_min_elevationYou named both sides, and the satellite is below the antenna's cutoff at at.
band_mismatchYou named both sides, and no radio matches an antenna: no antenna range covers its frequency, or their band letters disagree.
missing_antenna_diameterAt 4 GHz or above, the antenna has no antenna_diameter_m and its band has no default.
missing_frequencyNo frequency_ghz on the radio, no band on the radio or antenna, and no antenna frequency_ranges to give a band.
orbit_propagation_failedThe satellite's orbit could not be propagated to at from its current element set.
no_element_setThe orbit catalog has no element set for the satellite's norad_id. Give the satellite a tle.
invalid_element_setThe satellite's element set failed validation.
prediction_unavailableThe pair was past the 25-pair limit for one request, the model did not answer in time, the orbit catalog or visibility could not be read, or the model could not price the pair. Retry, or name both sides.

Tiers​

A fidelity tier labels how a model is served, not what a plan includes. This model is served at Silver.

Every plan that asks the model calls this same release, and GET /predictions takes no tier parameter.

Method and version​

Version 1 follows ITU-R P.618-13 and combines the rain, gas, cloud and scintillation terms into the total. The rain comes from the latest radar scan, then a radar nowcast, then weather-model forecasts, then a draw from the site's rain distribution, as Where the rain comes from describes. rain_source on each item says which.

Limitations and known failure modes​

  • Rain beyond the weather model is a draw, not a forecast. Past 72 hours, or where no model run covers the time, the rain term is drawn from the site's long-term distribution. It changes every hour per link and says nothing about the weather on that pass. Treat it as a planning figure only.
  • Outside radar coverage the rain starts from the weather model. Away from the contiguous US and Europe there is no observed or nowcast stage, so the first few hours use the model's forecast rather than a radar scan.
  • Nowcasts and model forecasts lose skill with lead. A nowcast for an hour ahead is less reliable than one for ten minutes, and a model forecast for three days out is less reliable than one for tomorrow. Check rain_lead_min.
  • Old element sets drift. The model propagates each satellite from its current element set, however far ahead of the set's epoch the requested time is. The further apart they are, the more orbit error reaches the elevation and the path.
  • Outside 1 to 55 GHz the ITU-R methods are stretched. ITU-R P.618 and P.838 are defined from 1 to 55 GHz. Above 55 GHz the model extrapolates them, and the rain term is likely too high. Below 1 GHz it holds rain and gas at their 1 GHz values, because the formulas break down there, and the ionospheric effects that matter most below 1 GHz, such as Faraday rotation and ionospheric scintillation from ITU-R P.531, are not modeled.
  • Defaults hide missing fields. The model prices a link with missing fields against its band's defaults, which describe a typical station rather than yours. assumptions lists them.
  • Declines are not zeros. Pairs the model cannot price appear in entity_errors. A 200 response can carry both items and errors.

Changelog​

VersionChange
v1First release. ITU-R P.618-13 with observed and nowcast rain traced along the slant path.