Space Weather Kp Observations for Monitoring Agents

Get structured NOAA planetary Kp observations with source timestamps and freshness checks for satellite and GNSS monitoring workflows.

This actor reads one official NOAA SWPC JSON feed. It supports object rows and a header followed by array rows. It selects the latest bounded window and returns it in ascending source-time order, oldest to newest within that window. The data is geomagnetic observation context for your own monitoring decisions. It provides no terrestrial forecast, earthquake data, imagery, human report, alerts prose or invented risk prediction.

What it returns

Field	Meaning
status	ok for a complete observation; error for a diagnostic
observedAt	NOAA time_tag normalized to UTC, ending in Z; never replaced with retrieval time
planetaryKp	NOAA Kp, a finite number from 0 to 9
runningAIndex	NOAA a_running, a nonnegative integer
stationCount	NOAA station_count, a nonnegative integer
sourceAgeHours	Retrieved time minus source time in hours, rounded to six decimals
stale	True when the unrounded source age strictly exceeds staleAfterHours
staleAfterHours	Threshold used for this run
retrievedAt	Actual UTC fetch completion time, distinct from observation time
sourceUrl	Fixed official feed URL
context	Structured domain, product, observation type and planetary scope
errorCode	Machine-readable diagnostic code, otherwise null
error	Sanitized diagnostic message, otherwise null

Diagnostics have null observation measurements. A malformed row can retain a valid source time and its freshness values; an absent/invalid time is null. Future source times are diagnostics with null age and stale values. Dated diagnostics participate in the latest window. Undated diagnostics occupy only unused slots after dated rows, keeping total output at or below maxItems.

Input

Prefilled input:

{"maxItems":3,"staleAfterHours":12}

Option	Default	Accepted values
maxItems	3	Integer 1–1000; cap on total dataset rows
staleAfterHours	12	Finite number 0–8760; hours

Empty or missing input uses these defaults. Unknown fields and wrong types fail with a clear message before fetching. No API key, location, credentials or configurable source URL is required.

Output example

One real observation from the local run; the complete three-row output is in sample_output.json:

{
  "status": "ok",
  "observedAt": "2026-10-06T06:00:00Z",
  "planetaryKp": 2.33,
  "runningAIndex": 9,
  "stationCount": 7,
  "sourceAgeHours": 3.147393,
  "stale": false,
  "staleAfterHours": 12,
  "retrievedAt": "2026-10-06T09:08:50.614309Z",
  "sourceUrl": "https://services.swpc.noaa.gov/products/noaa-planetary-k-index.json",
  "context": {
    "domain": "geomagnetic",
    "product": "noaa_planetary_k_index",
    "recordType": "observation",
    "spatialScope": "planetary"
  },
  "errorCode": null,
  "error": null
}

Results are stored in the default dataset for JSON, CSV or other Apify exports. A SUMMARY key-value record contains observation/error counts, event count, timing and whether the event budget reduced output. The output schema exposes the dataset items URL for API consumers.

Pricing

Proposed kp_observation event: $0.0001 per usable returned observation, or $0.10 per 1,000 events. Three usable prefilled observations cost $0.0003 in custom events. Diagnostic rows do not trigger this event. Stale but complete observations do trigger it. See PRICING.md for dated Store API evidence, different competitor event units and publisher configuration. Prices are proposed; the owner configures monetization before publication.

Limits and failure behavior

• Only the rolling data available in the upstream feed is returned; maxItems does not create missing history or increase source resolution. The cap is further reduced to the number of observations affordable under the event budget, selecting the latest affordable window.
• HTTP requests are serial, with a one-connection limit and a 15-second timeout per attempt. Transport failures, malformed JSON, HTTP 408/429 and server errors get three total attempts with waits of one and two seconds. Other HTTP failures and redirects are diagnosed without following another data source.
• Malformed items yield diagnostic rows. An empty feed, missing columns or exhausted source retries yield a diagnostic instead of an invented observation. Consumers should inspect status and stale rather than relying on run completion alone.
• NOAA availability, schema changes, source publication lag and the runtime clock affect freshness. Older data is returned with its measured age rather than silently treated as current.
• Repeated runs can return the same source observation. Match sourceUrl plus observedAt when correlating with your own telemetry. Each delivered usable row is a new billable event.

Use with AI agents / MCP

After publication, invoke this actor through the Apify API or Apify's MCP integration with the two input fields above. Read the returned dataset URL from the output schema. Treat status=ok as a usable source record; check stale and sourceAgeHours before combining it with satellite telemetry or GNSS quality measurements. context identifies the observation as planetary geomagnetic data; it does not classify local receiver impact or predict an outage.

Example agent request: "Get the latest three official NOAA planetary Kp observations using a 12-hour freshness threshold. Keep the source times and flag stale records before correlating with my GNSS measurements."

FAQ

Is observedAt the download time? No. It is NOAA's source time. Offset-free NOAA times are interpreted as UTC. retrievedAt records actual fetch completion.

Does stale predict a geomagnetic hazard? No. It describes data age against your chosen threshold.

Does it issue alerts or forecast satellite/GNSS risk? No. It supplies source observations for a monitoring agent to use alongside its own data.

Do errors cost an observation event? No. Diagnostic rows have status=error and do not invoke kp_observation. Publisher configuration keeps synthetic dataset charges absent or zero.

Local development

Dependencies are listed in requirements.txt. Tests additionally need pytest and jsonschema, already present in the prescribed shared environment; no packages were installed into it. From this actor directory, use PowerShell:

$env:APIFY_LOCAL_STORAGE_DIR = Join-Path (Get-Location) 'storage'
# storage/key_value_stores/default/INPUT.json is already prefilled.
& C:/GritWork/earn/.venv/Scripts/python.exe -m src
& C:/GritWork/earn/.venv/Scripts/python.exe -m pytest tests -q -p no:cacheprovider
apify validate-schema

The marked live smoke test accesses NOAA; unit and SDK storage tests use the saved real fixture. For a local charging simulation, set ACTOR_TEST_PAY_PER_EVENT=true; it logs events without billing an account. Default simulation event prices are $1, so use that mode to inspect counts rather than proposed dollar amounts.

Dockerfile uses apify/actor-python:3.12. actor.json retains the requested inputSchema/outputSchema references and also the documented input/output aliases so the installed CLI validates all three schemas.