Fetch solar conditions from HamQSL #92

webassets/apidocs/openapi.yml

@@ -13,8 +13,13 @@ info:
     
     ## Changelog
     
+    ### 1.2
+
+    * Added `/solar` endpoint for solar and propagation conditions.
+    * Added `solar_condition_providers` array to the `/status` response.
+
     ### 1.1
-    
+
     * Added Server-Sent Event API endpoints for spots and alerts.
     * Removed band colour and icon information from spots.
     * Moved activation_score from top-level in Spot and Alert to be part of the SIGRef
@@ -23,7 +28,7 @@ info:
   license:
     name: The Unlicense
     url: https://unlicense.org/#the-unlicense
-  version: v1.1
+  version: v1.2
 servers:
   - url: https://spothole.app/api/v1
 paths:
@@ -476,6 +481,11 @@ paths:
                     description: An array of all the alert providers.
                     items:
                       $ref: '#/components/schemas/AlertProviderStatus'
+                  solar_condition_providers:
+                    type: array
+                    description: An array of all the solar conditions providers.
+                    items:
+                      $ref: '#/components/schemas/SolarConditionsProviderStatus'
 
 
   /options:
@@ -772,6 +782,22 @@ paths:
                 example: "Failed"
 
 
+  /solar:
+    get:
+      tags:
+        - General
+      summary: Get solar and propagation conditions
+      description: Returns the current solar conditions and HF/VHF propagation condition summaries. This data is sourced from external providers (e.g. HamQSL) and updated periodically. All fields may be null if no provider has successfully fetched data yet.
+      operationId: solar
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SolarConditions'
+
+
 components:
   schemas:
     Source:
@@ -1328,4 +1354,136 @@ components:
         ref_regex:
           type: string
           description: Regex that matches this SIG's reference IDs. Generally for Spothole's own internal use, clients probably won't need this.
-          example: "[A-Z]{2}\\-\\d+"
+          example: "[A-Z]{2}\\-\\d+"
+
+    HFBandCondition:
+      type: object
+      description: HF propagation conditions for a group of bands at a particular time of day.
+      properties:
+        band:
+          type: string
+          description: Band group name as used by the data source, e.g. "80m-40m", "30m-20m", "17m-15m", "10m-6m".
+          example: "80m-40m"
+        time:
+          type: string
+          description: Time of day these conditions apply to.
+          enum:
+            - day
+            - night
+          example: day
+        condition:
+          type: string
+          description: Propagation condition assessment.
+          enum:
+            - Good
+            - Fair
+            - Poor
+          example: Good
+
+    VHFCondition:
+      type: object
+      description: A VHF propagation phenomenon and its current condition.
+      properties:
+        phenomenon:
+          type: string
+          description: The name of the propagation phenomenon, e.g. "E-Skip", "Sporadic E".
+          example: "E-Skip"
+        location:
+          type: string
+          description: The geographic region this condition applies to, e.g. "Europe", "N America".
+          example: "Europe"
+        condition:
+          type: string
+          description: The current condition for this phenomenon and location.
+          example: "Band Closed"
+
+    SolarConditions:
+      type: object
+      description: Current solar and propagation conditions. All fields may be null if no provider has successfully fetched data yet.
+      properties:
+        updated:
+          type: number
+          description: Time that the data was last updated, UTC seconds since UNIX epoch
+          example: 1759579508
+        sfi:
+          type: integer
+          description: Solar Flux Index (SFI). Higher values generally indicate better HF propagation.
+          example: 170
+        a_index:
+          type: integer
+          description: A-index — daily geomagnetic activity index. Higher values indicate more disturbed conditions.
+          example: 7
+        k_index:
+          type: integer
+          description: K-index — 3-hour geomagnetic activity index, 0–9. Values of 5 or above indicate a geomagnetic storm.
+          example: 2
+        x_ray:
+          type: string
+          description: Current X-ray flux class, e.g. "B2.3", "C1.0", "M5.0".
+          example: "B2.3"
+        proton_flux:
+          type: integer
+          description: Proton flux level.
+          example: 1
+        electron_flux:
+          type: integer
+          description: Electron flux level.
+          example: 631
+        aurora:
+          type: integer
+          description: Aurora activity level.
+          example: 5
+        aurora_latitude:
+          type: number
+          description: Latitude in degrees of the equatorward boundary of the aurora.
+          example: 66.3
+        sunspots:
+          type: integer
+          description: Current sunspot count.
+          example: 87
+        solar_wind:
+          type: number
+          description: Solar wind speed in km/s.
+          example: 356.6
+        magnetic_field:
+          type: number
+          description: Interplanetary magnetic field (IMF) strength in nT.
+          example: 2.5
+        geomag_field:
+          type: string
+          description: Geomagnetic field condition summary.
+          example: "Active"
+        geomag_noise:
+          type: string
+          description: Geomagnetic background noise level on HF, using S-units.
+          example: "S0"
+        hf_conditions:
+          type: array
+          description: HF propagation condition assessments by band group and time of day.
+          items:
+            $ref: '#/components/schemas/HFBandCondition'
+        vhf_conditions:
+          type: array
+          description: VHF propagation condition assessments by phenomenon and location.
+          items:
+            $ref: '#/components/schemas/VHFCondition'
+
+    SolarConditionsProviderStatus:
+      type: object
+      properties:
+        name:
+          type: string
+          description: The name of the provider.
+          example: HamQSL
+        enabled:
+          type: boolean
+          description: Whether the provider is enabled or not.
+          example: true
+        status:
+          type: string
+          description: The status of the provider.
+          example: OK
+        last_updated:
+          type: number
+          description: The last time at which this provider received data, UTC seconds since UNIX epoch. If this is zero, the provider has never updated.
+          example: 1759579508