Helioviewer Events API

Solar Event Data Platform

API Documentation

Version 2.0

Welcome to the Helioviewer Events API. This API provides access to solar event data from multiple sources.

Supported Sources & Timestamp Formats

Supported Sources

SourceDescription
CCMCCommunity Coordinated Modeling Center (DONKI, FlareScoreboard)
HEKHeliophysics Event Knowledgebase
WSAWang-Sheeley-Arge model forecasts (CCMC WSA dashboard): coronal-hole maps and magnetic-connectivity footpoints
RHESSIReuven Ramaty High Energy Solar Spectroscopic Imager

Source names are case-insensitive in all endpoints.

Accepted Timestamp Formats

FormatExample
Unix timestamp1705314645
ISO 8601 with microseconds & timezone2024-01-15T10:30:45.123456+00:00
ISO 8601 with milliseconds & Z2024-01-15T10:30:45.123Z
ISO 8601 with timezone2024-01-15T10:30:45+00:00
ISO 8601 with Z2024-01-15T10:30:45Z
ISO 8601 without timezone2024-01-15T10:30:45
Space-separated2024-01-15 10:30:45
PHP strtotime fallback2024-01-15, now, etc.

Event Data

GET /api/v1/events/recents Recent events

Get the last 100 updated events with enhanced data.

import requests

response = requests.get(
    "https://events.helioviewer.org/api/v1/events/recents"
)
events = response.json()

Example response:

[{
  "url": "https://events.helioviewer.org/api/v1/events/019d0c00-1985-...",
  "path": "CCMC>>Solar Flare Predictions>>ASSA",
  "start": "2025-06-03 00:00:00",
  "end": "2025-06-03 12:00:00",
  "hv_hpc_x": 37,
  "hv_hpc_y": -14,
  "label": "ASSA | AR 14099\nC: 26%\nM: 6%\nX: 1%",
  "coordinate_system": "stonyhurst",
  "regions": [{"organization": "NOAA", "external_id": "14099", ...}],
  "source_url": "https://events.helioviewer.org/api/v1/events/019d0c00-.../source",
  "views": [{"name": "Flare Prediction", "content": {"C": 0.26, "M": 0.06, ...}}],
  "link": {"url": "...", "text": "Helioviewer Events API JSON"}
}, ... // 100 events]
GET /api/v1/events/{source}/observation/{timestamp} Events by observation time

Get events from a specific source active at a given observation time. For WSA and Solar Flare Predictions, only the newest forecast per path issued at or before the observation time is returned.

ParameterTypeDescription
sourcepathEvent source (CCMC, HEK, RHESSI, WSA)
timestamppathObservation time (any supported format)
import requests

response = requests.get(
    "https://events.helioviewer.org/api/v1/events/HEK/observation/2025-03-15T12:00:00Z"
)
events = response.json()

Example response:

[{
  "url": "https://events.helioviewer.org/api/v1/events/019c3d8f-0932-...",
  "path": "HEK>>Active Region>>HMI SHARP",
  "start": "2025-03-15 08:00:00",
  "end": "2025-03-15 12:00:00",
  "hv_hpc_x": -806.97,
  "hv_hpc_y": 440.01,
  "visible": true,
  "label": "HMI SHARP 12923",
  "coordinate_system": "helioprojective",
  "regions": [{"organization": "NOAA", "external_id": "14033", ...}],
  ...
}, ... // 49 events]

visible says whether the event's center faces the observer at the requested time. An event that has rotated behind the limb is still returned, flagged visible: false — the client decides how to draw it. Far-side footprint vertices carry their own "visible": false beside x/y; front-side vertices have no such key, and a missing key always means visible.

GET /api/v1/events/{uuid} Single event by UUID

Get a single event by its UUID with full details.

ParameterTypeDescription
uuidpathEvent UUID
import requests

uuid = "019d0c00-1985-7131-84eb-24bc34a750ad"
response = requests.get(
    f"https://events.helioviewer.org/api/v1/events/{uuid}"
)
event = response.json()

Example response:

{
  "url": "https://events.helioviewer.org/api/v1/events/019d0c00-1985-...",
  "path": "CCMC>>Solar Flare Predictions>>ASSA",
  "start": "2025-06-03 00:00:00",
  "peak": "2025-06-03 12:00:00",
  "end": "2025-06-03 12:00:00",
  "coordinate_time": "2025-06-03 00:00:00",
  "hv_hpc_x": 37,
  "hv_hpc_y": -14,
  "label": "ASSA | AR 14099\nC: 26%\nM: 6%\nX: 1%",
  "coordinate_system": "stonyhurst",
  "regions": [{"organization": "NOAA", "external_id": "14099", ...}],
  "source_url": ".../source",
  "views": [{"name": "Flare Prediction", "content": {"C": 0.26, "M": 0.06, "X": 0.01, ...}}],
  "link": {"url": "...", "text": "Helioviewer Events API JSON"}
}
GET /api/v1/events/{uuid}/source Raw source data

Get the raw source data for an event (original data from the provider before normalization).

ParameterTypeDescription
uuidpathEvent UUID
import requests

uuid = "019d0c00-1985-7131-84eb-24bc34a750ad"
response = requests.get(
    f"https://events.helioviewer.org/api/v1/events/{uuid}/source"
)
source_data = response.json()

Example response (CCMC FlareScoreboard):

{
  "start_window": "2025-06-03T00:00:00.000Z",
  "end_window": "2025-06-03T12:00:00.000Z",
  "issue_time": "2025-06-03T00:00:00.000Z",
  "C": 0.26,
  "M": 0.06,
  "CPlus": null,
  "MPlus": null,
  "X": 0.01,
  "NOAARegionId": null,
  "NOAALocationTime": null,
  "NOAALatitude": null,
  "NOAALongitude": null,
  "ModelRegionId": 2,
  "ModelLocationTime": "2025-06-03T00:00:00.000Z",
  "ModelLatitude": -13,
  "ModelLongitude": 37
}

Active Regions

GET /api/v1/regions All regions

Get all active regions across all organizations.

import requests

response = requests.get(
    "https://events.helioviewer.org/api/v1/regions"
)
data = response.json()
regions = data["regions"]

Example response:

{
  "regions": [{
    "id": 5783,
    "organization": "NOAA",
    "external_id": "14548",
    "event_count": 7,
    "first_seen": "2026-10-14 16:55:03",
    "last_updated": "2026-10-14 16:55:03",
    "latest_event_start": "2026-10-14 00:00:00"
  }, ... // 3199 total regions]
}
GET /api/v1/regions/{organization}/{external_id} Events for a region

Get events associated with a specific active region.

ParameterTypeDescription
organizationpathRegion organization: NOAA or HARP
external_idpathRegion identifier (e.g., 14188)
import requests

response = requests.get(
    "https://events.helioviewer.org/api/v1/regions/NOAA/14188"
)
data = response.json()
region = data["region"]
events = data["events"]

Example response:

{
  "region": {
    "organization": "NOAA",
    "external_id": "14188",
    "event_count": 100
  },
  "events": [{
    "url": "https://events.helioviewer.org/api/v1/events/019981d6-c0db-...",
    "path": "CCMC>>Solar Flare Predictions>>DAFFS",
    "start": "2025-08-31 23:54:00",
    "end": "2025-09-01 23:54:00",
    "hv_hpc_x": 78,
    "hv_hpc_y": -9,
    "label": "DAFFS | AR 14188\nC+: 0.3%\nM+: 0.03%\nX: 0.06%",
    "coordinate_system": "stonyhurst",
    ...
  }, ... // 100 events total]
}

Helioviewer.org Integration

GET /helioviewer/events/{source}/observation/{timestamp} Legacy observation format

Get events active at a specific observation time, grouped by event type with nested detection method groups. Solar Flare Predictions return only the newest forecast per model issued at or before the observation time.

ParameterTypeDescription
sourcepathEvent source (CCMC, HEK, RHESSI) — WSA is not implemented on this legacy endpoint; use /api/v1/events/WSA/observation/{timestamp}
timestamppathObservation time (any supported format)
import requests

response = requests.get(
    "https://events.helioviewer.org/helioviewer/events/HEK/observation/2025-03-15T12:00:00Z"
)
data = response.json()

Example response:

[
  {
    "name": "Active Region",
    "pin": "AR",
    "groups": [{
      "name": "HMI SHARP",
      "contact": "turmon@jpl.nasa.gov",
      "data": [{
        "id": "019c3d8f-0932-...",
        "path": "HEK>>Active Region>>HMI SHARP",
        "start": "2025-03-15T08:00:00",
        "end": "2025-03-15T12:00:00",
        "hv_hpc_x": -806.97,
        "hv_hpc_y": 440.01,
        "visible": true,
        "label": "HMI SHARP 12923",
        ...
      }, ...]
    }]
  },
  ... // 31 event type groups
]
POST /helioviewer/events/from/{from}/to/{to} Events by path prefixes

Get events matching path prefixes within a time range. Returns flat list with Helioviewer-specific fields; hv_hpc_x/hv_hpc_y are the arcsec snapshot at the event's own coordinate_time, and hv_labels_formatted holds the tooltip rows (HEK source fields, or the WSA view).

ParameterTypeDescription
frompathStart time (Unix timestamp)
topathEnd time (Unix timestamp)
pathsbody (JSON)Array of event path prefixes; an entry ending in >><uuid> selects that single event by id
import requests

response = requests.post(
    "https://events.helioviewer.org/helioviewer/events/from/1741996800/to/1742083200",
    json={"paths": ["HEK>>Flare"]}
)
data = response.json()

Example response:

{
  "paths": ["HEK>>Flare"],
  "from": 1741996800,
  "to": 1742083200,
  "count": 33,
  "events": [{
    "x": 1741999352000,
    "x2": 1741999592000,
    "y": 1,
    "event_starttime": "2025-03-15 00:42:32",
    "event_endtime": "2025-03-15 00:46:32",
    "event_peaktime": "2025-03-15 00:44:20",
    "hv_hpc_x": 345.6,
    "hv_hpc_y": 192,
    "event_type": "FL",
    "frm_name": "Flare Detective - Trigger Module",
    "concept": "Flare",
    "hv_labels_formatted": {"Peak Flux": "37.4 DN/sec/pixel"},
    ...
  }, ...]
}
POST /helioviewer/distributions/size/{size}/from/{from}/to/{to} Event count distributions

Get event count distributions aggregated into time buckets.

ParameterTypeDescription
sizepathBucket size: 30m, h, D, W, M, Y
frompathStart time (Unix timestamp)
topathEnd time (Unix timestamp)
pathsbody (JSON)Array of event path prefixes
import requests

response = requests.post(
    "https://events.helioviewer.org/helioviewer/distributions/size/D/from/1741996800/to/1742256000",
    json={"paths": ["HEK>>Flare", "CCMC>>DONKI>>CME"]}
)
data = response.json()

Example response:

{
  "paths": ["HEK>>Flare", "CCMC>>DONKI>>CME"],
  "size": "D",
  "from": 1741996800,
  "to": 1742256000,
  "event_types": ["CE", "FL"],
  "buckets": [
    {"start": 1741996800, "counts": {"CE": 9, "FL": 33}},
    {"start": 1742083200, "counts": {"CE": 13, "FL": 73}},
    {"start": 1742169600, "counts": {"CE": 16, "FL": 79}},
    {"start": 1742256000, "counts": {"CE": 16, "FL": 49}}
  ]
}
POST /helioviewer/events/frames_with_selections Batch observations by selections

Batch observations filtered by a flexible selections array of path prefixes. Static event data (arcsec snapshot base) sent once in events; each timestamp carries only that frame's dx/dy arcsec offset from it — client renders pin = center + (dx,dy). footprint is a list of polygons, shifted by the same delta.

ParameterTypeDescription
timestampsbody (JSON)Array of datetime strings (max 150)
selectionsbody (JSON)Array of path-prefix strings (max 200)
import requests

response = requests.post(
    "https://events.helioviewer.org/helioviewer/events/frames_with_selections",
    json={
        "timestamps": ["2025-03-15 11:00:00", "2025-03-15 12:00:00"],
        "selections": ["HEK>>Flare", "CCMC>>DONKI>>CME"]
    }
)
data = response.json()

Example response:

{
  "events": {
    "019c3d8f-...": {
      "path": "HEK>>Flare>>SSW Latest Events",
      "label": "...", "start": "2025-03-15T11:50:00", "end": "2025-03-15T12:10:00",
      "hv_hpc_x": -123.4, "hv_hpc_y": 567.8, "footprint": [[...]],
      "type": "FL", "pin": "FL"
    }, ...
  },
  "timestamps": {
    "2025-03-15 11:00:00": {"019c3d8f-...": {"dx": 4.4, "dy": 2.4, "visible": true}, ...},
    "2025-03-15 12:00:00": { ... }
  }
}

A selection matches every event whose path equals the prefix or starts with that prefix. Max 150 timestamps and 200 selections per request.

visible is per frame: whether the event's center faces the observer at that timestamp, so a movie can fade a region as it rotates over the limb without re-fetching its footprint. Far-side vertices in the events footprint base carry their own "visible": false.

Interactive Tools

PathDescription
/statsStatistics dashboard
/active-regionsActive regions search tool
/api-docsOpenAPI reference with Swagger UI (openapi.json)

Documentation

For more information, visit the Helioviewer website.