Lookup for sig_ref data #73

webassets/apidocs/openapi.yml

@@ -17,7 +17,7 @@ paths:
   /spots:
     get:
       tags:
-        - spots
+        - Spots
       summary: Get spots
       description: The main API call that retrieves spots from the system. Supply this with no query parameters to retrieve all spots known to the system. Supply query parameters to filter what is retrieved.
       operationId: spots
@@ -247,7 +247,7 @@ paths:
   /alerts:
     get:
       tags:
-        - alerts
+        - Alerts
       summary: Get alerts
       description: Retrieves alerts (indications of upcoming activations) from the system. Supply this with no query parameters to retrieve all alerts known to the system. Supply query parameters to filter what is retrieved.
       operationId: spots
@@ -355,7 +355,7 @@ paths:
   /status:
     get:
       tags:
-        - general
+        - General
       summary: Get server status
       description: Query information about the server for use in a diagnostics display.
       operationId: status
@@ -432,7 +432,7 @@ paths:
   /options:
     get:
       tags:
-        - general
+        - General
       summary: Get enumeration options
       description: Retrieves the list of options for various enumerated types, which can be found in the spots and also provided back to the API as query parameters. While these enumerated options are defined in this spec anyway, providing them in an API call allows us to define extra parameters, like the colours associated with bands, and also allows clients to set up their filters and features without having to have internal knowledge about, for example, what bands the server knows about.
       operationId: options
@@ -488,10 +488,92 @@ paths:
                     example: true
 
 
+  /lookup/sigref:
+    get:
+      tags:
+        - Utilities
+      summary: Look up SIG Ref details
+      description: Perform a lookup of data about a certain reference, providing the SIG and the ID of the reference.
+      operationId: sigref
+      parameters:
+        - name: sig
+          in: query
+          description: Special Interest Group (SIG), e.g. outdoor activity programme such as POTA
+          required: true
+          type: string
+          enum:
+            - POTA
+            - SOTA
+            - WWFF
+            - WWBOTA
+            - GMA
+            - HEMA
+            - WCA
+            - MOTA
+            - SIOTA
+            - ARLHS
+            - ILLW
+            - ZLOTA
+            - IOTA
+            - WOTA
+            - BOTA
+            - WAB
+            - WAI
+          example: POTA
+        - name: sig_ref_id
+          in: query
+          description: ID of a reference in that SIG
+          required: true
+          type: string
+          example: GB-0001
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: SIG reference name
+                    example: Null Country Park
+                  url:
+                    type: string
+                    description: SIG reference URL, which the user can look up for more information
+                    example: "https://pota.app/#/park/GB-0001"
+                  grid:
+                    type: string
+                    description: Maidenhead grid locator for the reference.
+                    example: IO91aa
+                  latitude:
+                    type: number
+                    description: Latitude of the reference, in degrees.
+                    example: 51.2345
+                  longitude:
+                    type: number
+                    description: Longitude of the reference, in degrees.
+                    example: -1.2345
+        '404':
+          description: Reference not found, or SIG not supported
+          content:
+            application/json:
+              schema:
+                type: string
+                example: "Failed"
+        '422':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                type: string
+                example: "Failed"
+
+
   /spot:
     post:
       tags:
-        - spots
+        - Spots
       summary: Add a spot
       description: "Supply a new spot object, which will be added to the system. Currently, this will not be reported up the chain to a cluster, POTA, SOTA etc. This may be introduced in a future version. cURL example: `curl --request POST --header \"Content-Type: application/json\" --data '{\"dx_call\":\"M0TRT\",\"time\":1760019539, \"freq\":14200000, \"comment\":\"Test spot please ignore\", \"de_call\":\"M0TRT\"}' https://spothole.app/api/v1/spot`"
       operationId: spot