# Space Weather Kp Observations for Monitoring Agents (`grit-77/space-weather-kp`) Actor

NOAA SWPC planetary Kp observation feed for satellite and GNSS monitoring data. Export structured JSON with source timestamps and freshness checks; no forecast or risk prediction.

- **URL**: https://apify.com/grit-77/space-weather-kp.md
- **Developed by:** [Grit](https://apify.com/grit-77) (community)
- **Categories:** Other, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.10 / 1,000 kp observations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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](https://services.swpc.noaa.gov/products/noaa-planetary-k-index.json). 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:

```json
{"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](sample_output.json):

```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](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:

```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.

# Actor input Schema

## `maxItems` (type: `integer`):

Latest dated rows to retain, including malformed dated observations. Undated diagnostics use remaining slots. Hard limit on total dataset rows.

## `staleAfterHours` (type: `number`):

Flag an observation stale when its source age strictly exceeds this threshold. Age uses source time and actual retrieval time, in UTC. Zero flags any past observation.

## Actor input object example

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

# Actor output Schema

## `dataset` (type: `string`):

Latest NOAA planetary Kp observations, UTC source age, staleness and diagnostic rows.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 3,
    "staleAfterHours": 12
};

// Run the Actor and wait for it to finish
const run = await client.actor("grit-77/space-weather-kp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "maxItems": 3,
    "staleAfterHours": 12,
}

# Run the Actor and wait for it to finish
run = client.actor("grit-77/space-weather-kp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 3,
  "staleAfterHours": 12
}' |
apify call grit-77/space-weather-kp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,grit-77/space-weather-kp"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/H5BaYK5wh6W8WtOTw/builds/QU0hfakoDCitGKiVh/openapi.json