Modify the backend so that instead of using the server owner's QRZ & HamQTH credentials, it instead requires them to be provided by the client (if none are provided, the lookups do not occur.)

2026-05-30 17:35:11 +00:00 · 2026-05-09 15:43:22 +01:00
parent 0988a567b8
commit f81ef4347f
18 changed files with 385 additions and 174 deletions
--- a/webassets/apidocs/openapi.yml
+++ b/webassets/apidocs/openapi.yml
@@ -13,6 +13,10 @@ info:
    
    ## Changelog
    
+    ### 1.3
+
+    * `/spots`, `/spots/stream`, `/alerts`, `/alerts/stream`, and `/lookup/call` now accept optional QRZ.com and HamQTH credentials as query parameters. When supplied, returned data is enriched with operator name, home location etc. from those services.
+
    ### 1.2

    * Added `/dxstats` endpoint for inter-continent DX spot statistics.
@@ -29,7 +33,7 @@ info:
  license:
    name: The Unlicense
    url: https://unlicense.org/#the-unlicense
-  version: v1.2
+  version: v1.3
 servers:
  - url: https://spothole.app/api/v1
 paths:
@@ -38,7 +42,7 @@ paths:
      tags:
        - 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.
+      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. If QRZ.com or HamQTH credentials are supplied, returned spots will be enriched with operator name, home location etc. from those services.
      operationId: spots
      parameters:
        - name: limit
@@ -160,6 +164,12 @@ paths:
          schema:
            type: boolean
            default: true
+        - $ref: '#/components/parameters/QrzUsername'
+        - $ref: '#/components/parameters/QrzPassword'
+        - $ref: '#/components/parameters/QrzSessionKey'
+        - $ref: '#/components/parameters/HamqthUsername'
+        - $ref: '#/components/parameters/HamqthPassword'
+        - $ref: '#/components/parameters/HamqthSessionId'
      responses:
        '200':
          description: Success
@@ -175,7 +185,7 @@ paths:
      tags:
        - Spots
      summary: Get spot stream
-      description: Request a Server-Sent Event stream which will return individual spots immediately when they are added to the system. Only spots that match the provided filters will be returned.
+      description: Request a Server-Sent Event stream which will return individual spots immediately when they are added to the system. Only spots that match the provided filters will be returned. If QRZ.com or HamQTH credentials are supplied, streamed spots will be enriched with operator name, home location etc. from those services.
      operationId: spots-stream
      parameters:
        - name: source
@@ -266,6 +276,12 @@ paths:
          schema:
            type: boolean
            default: true
+        - $ref: '#/components/parameters/QrzUsername'
+        - $ref: '#/components/parameters/QrzPassword'
+        - $ref: '#/components/parameters/QrzSessionKey'
+        - $ref: '#/components/parameters/HamqthUsername'
+        - $ref: '#/components/parameters/HamqthPassword'
+        - $ref: '#/components/parameters/HamqthSessionId'
      responses:
        '200':
          description: Success
@@ -280,7 +296,7 @@ paths:
      tags:
        - 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.
+      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. If QRZ.com or HamQTH credentials are supplied, returned alerts will be enriched with operator names from those services.
      operationId: alerts
      parameters:
        - name: limit
@@ -337,6 +353,12 @@ paths:
          required: false
          schema:
            type: string
+        - $ref: '#/components/parameters/QrzUsername'
+        - $ref: '#/components/parameters/QrzPassword'
+        - $ref: '#/components/parameters/QrzSessionKey'
+        - $ref: '#/components/parameters/HamqthUsername'
+        - $ref: '#/components/parameters/HamqthPassword'
+        - $ref: '#/components/parameters/HamqthSessionId'
      responses:
        '200':
          description: Success
@@ -353,7 +375,7 @@ paths:
      tags:
        - Alerts
      summary: Get alert stream
-      description: Request a Server-Sent Event stream which will return individual alerts immediately when they are added to the system. Only alerts that match the provided filters will be returned.
+      description: Request a Server-Sent Event stream which will return individual alerts immediately when they are added to the system. Only alerts that match the provided filters will be returned. If QRZ.com or HamQTH credentials are supplied, streamed alerts will be enriched with operator names from those services.
      operationId: alerts-stream
      parameters:
        - name: max_duration
@@ -398,6 +420,12 @@ paths:
          required: false
          schema:
            type: string
+        - $ref: '#/components/parameters/QrzUsername'
+        - $ref: '#/components/parameters/QrzPassword'
+        - $ref: '#/components/parameters/QrzSessionKey'
+        - $ref: '#/components/parameters/HamqthUsername'
+        - $ref: '#/components/parameters/HamqthPassword'
+        - $ref: '#/components/parameters/HamqthSessionId'
      responses:
        '200':
          description: Success
@@ -607,7 +635,7 @@ paths:
      tags:
        - Utilities
      summary: Look up callsign details
-      description: Perform a lookup of data about a certain callsign, using any of the lookup services available to the Spothole server.
+      description: Perform a lookup of data about a certain callsign, using any of the lookup services available to the Spothole server. If QRZ.com or HamQTH credentials are supplied, the response will be able to use these services to perform a lookup.
      operationId: call
      parameters:
        - name: call
@@ -616,6 +644,12 @@ paths:
          required: true
          type: string
          example: M0TRT
+        - $ref: '#/components/parameters/QrzUsername'
+        - $ref: '#/components/parameters/QrzPassword'
+        - $ref: '#/components/parameters/QrzSessionKey'
+        - $ref: '#/components/parameters/HamqthUsername'
+        - $ref: '#/components/parameters/HamqthPassword'
+        - $ref: '#/components/parameters/HamqthSessionId'
      responses:
        '200':
          description: Success
@@ -838,6 +872,50 @@ paths:
                example: "Failed"

 components:
+  parameters:
+    QrzUsername:
+      name: qrz_username
+      in: query
+      description: "QRZ.com username for online callsign lookup, which will enrich the returned spots and alerts with extra data. Requires a QRZ.com XML Subscriber (paid) account. Supply together with `qrz_password`, or supply `qrz_session_key` instead."
+      required: false
+      schema:
+        type: string
+    QrzPassword:
+      name: qrz_password
+      in: query
+      description: "QRZ.com password. Supply together with `qrz_username`."
+      required: false
+      schema:
+        type: string
+    QrzSessionKey:
+      name: qrz_session_key
+      in: query
+      description: "A pre-obtained QRZ.com XML session key, as an alternative to supplying `qrz_username` and `qrz_password`. See https://www.qrz.com/docs/xml/current_spec.html for details on how to obtain one for the user."
+      required: false
+      schema:
+        type: string
+    HamqthUsername:
+      name: hamqth_username
+      in: query
+      description: "HamQTH username for online callsign lookup, which will enrich the returned spots and alerts with extra data. Supply together with `hamqth_password`, or supply `hamqth_session_id` instead."
+      required: false
+      schema:
+        type: string
+    HamqthPassword:
+      name: hamqth_password
+      in: query
+      description: "HamQTH password. Supply together with `hamqth_username`."
+      required: false
+      schema:
+        type: string
+    HamqthSessionId:
+      name: hamqth_session_id
+      in: query
+      description: "A pre-obtained HamQTH session ID, as an alternative to supplying `hamqth_username` and `hamqth_password`. See https://www.hamqth.com/developers.php for details on how to retrieve one for a user."
+      required: false
+      schema:
+        type: string
+
  schemas:
    Source:
      type: string