mirror of
https://git.ianrenton.com/ian/spothole.git
synced 2026-09-20 14:27:42 +00:00
Giant refactor to rebrand "SIG" as "Activity" anywhere that doesn't touch API or config file (which is to be addressed in a future breaking change). #147
This commit is contained in:
Ian Renton
+99
-94
@@ -109,7 +109,7 @@ tags:
|
||||
- name: General
|
||||
description: Server status and enumeration options.
|
||||
- name: Utilities
|
||||
description: Utility lookups for callsigns, SIG references, and Maidenhead grids.
|
||||
description: Utility lookups for callsigns, activity references, and Maidenhead grids.
|
||||
|
||||
paths:
|
||||
/spots:
|
||||
@@ -129,9 +129,9 @@ paths:
|
||||
- $ref: '#/components/parameters/SpotMaxAge'
|
||||
- $ref: '#/components/parameters/SpotReceivedSince'
|
||||
- $ref: '#/components/parameters/SpotSource'
|
||||
- $ref: '#/components/parameters/SpotSig'
|
||||
- $ref: '#/components/parameters/SpotNeedsSig'
|
||||
- $ref: '#/components/parameters/SpotNeedsSigRef'
|
||||
- $ref: '#/components/parameters/SpotActivity'
|
||||
- $ref: '#/components/parameters/SpotNeedsActivity'
|
||||
- $ref: '#/components/parameters/SpotNeedsActivityRef'
|
||||
- $ref: '#/components/parameters/SpotBand'
|
||||
- $ref: '#/components/parameters/SpotMode'
|
||||
- $ref: '#/components/parameters/SpotModeType'
|
||||
@@ -171,9 +171,9 @@ paths:
|
||||
operationId: spots-stream
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/SpotSource'
|
||||
- $ref: '#/components/parameters/SpotSig'
|
||||
- $ref: '#/components/parameters/SpotNeedsSig'
|
||||
- $ref: '#/components/parameters/SpotNeedsSigRef'
|
||||
- $ref: '#/components/parameters/SpotActivity'
|
||||
- $ref: '#/components/parameters/SpotNeedsActivity'
|
||||
- $ref: '#/components/parameters/SpotNeedsActivityRef'
|
||||
- $ref: '#/components/parameters/SpotBand'
|
||||
- $ref: '#/components/parameters/SpotMode'
|
||||
- $ref: '#/components/parameters/SpotModeType'
|
||||
@@ -218,7 +218,7 @@ paths:
|
||||
- $ref: '#/components/parameters/AlertDxpeditionsSkipMaxDurationCheck'
|
||||
- $ref: '#/components/parameters/AlertContestsSkipMaxDurationCheck'
|
||||
- $ref: '#/components/parameters/AlertSource'
|
||||
- $ref: '#/components/parameters/AlertSig'
|
||||
- $ref: '#/components/parameters/AlertActivity'
|
||||
- $ref: '#/components/parameters/AlertDxContinent'
|
||||
- $ref: '#/components/parameters/AlertDxCallIncludes'
|
||||
- $ref: '#/components/parameters/AlertTextIncludes'
|
||||
@@ -254,7 +254,7 @@ paths:
|
||||
- $ref: '#/components/parameters/AlertDxpeditionsSkipMaxDurationCheck'
|
||||
- $ref: '#/components/parameters/AlertContestsSkipMaxDurationCheck'
|
||||
- $ref: '#/components/parameters/AlertSource'
|
||||
- $ref: '#/components/parameters/AlertSig'
|
||||
- $ref: '#/components/parameters/AlertActivity'
|
||||
- $ref: '#/components/parameters/AlertDxContinent'
|
||||
- $ref: '#/components/parameters/AlertDxCallIncludes'
|
||||
- $ref: '#/components/parameters/AlertTextIncludes'
|
||||
@@ -392,24 +392,24 @@ paths:
|
||||
get:
|
||||
tags:
|
||||
- Utilities
|
||||
summary: Look up SIG ref details
|
||||
summary: Look up activity ref details
|
||||
description: >
|
||||
Perform a lookup of data about a certain reference, providing the SIG and the ID of the
|
||||
reference. A SIGRef structure will be returned containing the SIG and ID, plus any other
|
||||
Perform a lookup of data about a certain reference, providing the activity and the ID of the
|
||||
reference. An ActivityRef structure will be returned containing the activity and ID, plus any other
|
||||
information Spothole could find about it.
|
||||
operationId: sigref
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/SigRefSig'
|
||||
- $ref: '#/components/parameters/SigRefId'
|
||||
- $ref: '#/components/parameters/ActivityRefLookupActivity'
|
||||
- $ref: '#/components/parameters/ActivityRefLookupId'
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SIGRef'
|
||||
$ref: '#/components/schemas/ActivityRef'
|
||||
'422':
|
||||
description: Validation error e.g. SIG not supported or reference format incorrect
|
||||
description: Validation error e.g. activity not supported or reference format incorrect
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
@@ -452,7 +452,7 @@ paths:
|
||||
description: >
|
||||
Supply a JSON object containing a `spot` sub-object (the spot data) and an optional `handling` sub-object
|
||||
containing server-side instructions such as upstream submission). Check `spot_submit_providers` in the
|
||||
`/options` response to see which SIGs and providers support upstream submission. cURL example:
|
||||
`/options` response to see which activities and providers support upstream submission. cURL example:
|
||||
`curl --request POST --header \"Content-Type: application/json\" --data '{\"spot\":{\"dx_call\":\"M0TRT\",\"time\":1760019539,\"freq\":14200000,\"comment\":\"Test spot please ignore\",\"de_call\":\"M0TRT\"}}' https://spothole.app/api/v2/spot`"
|
||||
operationId: spot
|
||||
requestBody:
|
||||
@@ -550,37 +550,37 @@ components:
|
||||
named some sources like clusters differently, and provided multiple options.
|
||||
schema:
|
||||
$ref: "#/components/schemas/Source"
|
||||
SpotSig:
|
||||
SpotActivity:
|
||||
name: sig
|
||||
in: query
|
||||
description: >
|
||||
Limit the spots to only ones from one or more Special Interest Groups provided as an argument.
|
||||
To select more than one SIG, supply a comma-separated list. The special `sig` name `NO_SIG`
|
||||
matches spots with no sig set. You can use `sig=NO_SIG` to specifically only return generic
|
||||
spots with no associated SIG. You can also use combinations to request for example POTA + no
|
||||
SIG, but reject other SIGs. If you want to request 'every SIG and not No SIG', see the
|
||||
Limit the spots to only ones from one or more activities provided as an argument.
|
||||
To select more than one activity, supply a comma-separated list. The special `sig` name `NO_SIG`
|
||||
matches spots with no activity set. You can use `sig=NO_SIG` to specifically only return generic
|
||||
spots with no associated activity. You can also use combinations to request for example POTA + no
|
||||
activity, but reject other activities. If you want to request 'every activity and not No Activity', see the
|
||||
`needs_sig` query parameter for a shortcut.
|
||||
schema:
|
||||
$ref: "#/components/schemas/SIGNameIncludingNoSIG"
|
||||
SpotNeedsSig:
|
||||
$ref: "#/components/schemas/ActivityNameIncludingNoSig"
|
||||
SpotNeedsActivity:
|
||||
name: needs_sig
|
||||
in: query
|
||||
description: >
|
||||
Limit the spots to only ones with a Special Interest Group such as POTA. Because supplying all
|
||||
known SIGs as a `sigs` parameter is unwieldy, and leaving `sigs` blank will also return spots
|
||||
with *no* SIG, this parameter can be set true to return only spots with a SIG, regardless of
|
||||
Limit the spots to only ones with an activity such as POTA. Because supplying all
|
||||
known activities as a `sigs` parameter is unwieldy, and leaving `sigs` blank will also return spots
|
||||
with *no* activity, this parameter can be set true to return only spots with an activity, regardless of
|
||||
what it is, so long as it's not blank. This is the equivalent of supplying the `sig` query
|
||||
param with a list of every known SIG apart from the special `NO_SIG` value. This is what Field
|
||||
param with a list of every known activity apart from the special `NO_SIG` value. This is what Field
|
||||
Spotter uses to exclude generic cluster spots and only retrieve xOTA things.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
SpotNeedsSigRef:
|
||||
SpotNeedsActivityRef:
|
||||
name: needs_sig_ref
|
||||
in: query
|
||||
description: >
|
||||
Limit the spots to only ones which have at least one reference (e.g. a park reference) for
|
||||
Special Interest Groups such as POTA.
|
||||
activities such as POTA.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
@@ -714,15 +714,15 @@ components:
|
||||
comma-separated list.
|
||||
schema:
|
||||
$ref: "#/components/schemas/Source"
|
||||
AlertSig:
|
||||
AlertActivity:
|
||||
name: sig
|
||||
in: query
|
||||
description: >
|
||||
Limit the alerts to only ones from one or more Special Interest Groups. To select more than one
|
||||
SIG, supply a comma-separated list. The special value 'NO_SIG' can be included to return alerts
|
||||
specifically without an associated SIG (i.e. general DXpeditions).
|
||||
Limit the alerts to only ones from one or more activities. To select more than one
|
||||
activity, supply a comma-separated list. The special value 'NO_SIG' can be included to return alerts
|
||||
specifically without an associated activity (i.e. general DXpeditions).
|
||||
schema:
|
||||
$ref: "#/components/schemas/SIGNameIncludingNoSIG"
|
||||
$ref: "#/components/schemas/ActivityNameIncludingNoSig"
|
||||
AlertDxContinent:
|
||||
name: dx_continent
|
||||
in: query
|
||||
@@ -830,17 +830,17 @@ components:
|
||||
schema:
|
||||
type: string
|
||||
example: M0TRT
|
||||
SigRefSig:
|
||||
ActivityRefLookupActivity:
|
||||
name: sig
|
||||
in: query
|
||||
description: Special Interest Group (SIG), e.g. outdoor activity programme such as POTA
|
||||
description: Activity, e.g. outdoor activity programme such as POTA (still named "sig" in the API for backwards compatibility)
|
||||
required: true
|
||||
schema:
|
||||
$ref: "#/components/schemas/SIGName"
|
||||
SigRefId:
|
||||
$ref: "#/components/schemas/ActivityName"
|
||||
ActivityRefLookupId:
|
||||
name: id
|
||||
in: query
|
||||
description: ID of a reference in that SIG
|
||||
description: ID of a reference in that activity
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
@@ -876,7 +876,7 @@ components:
|
||||
- UKPacketNet
|
||||
example: POTA
|
||||
|
||||
SIGName:
|
||||
ActivityName:
|
||||
type: string
|
||||
enum:
|
||||
- POTA
|
||||
@@ -914,7 +914,7 @@ components:
|
||||
- Toilets
|
||||
example: POTA
|
||||
|
||||
SIGType:
|
||||
ActivityType:
|
||||
type: string
|
||||
enum:
|
||||
- WORLDWIDE
|
||||
@@ -922,14 +922,14 @@ components:
|
||||
- EVENT
|
||||
example: WORLDWIDE
|
||||
|
||||
SIGNameIncludingNoSIG:
|
||||
ActivityNameIncludingNoSig:
|
||||
oneOf:
|
||||
- $ref: "#/components/schemas/SIGName"
|
||||
- $ref: "#/components/schemas/ActivityName"
|
||||
- type: string
|
||||
enum: [ NO_SIG ]
|
||||
example: POTA
|
||||
|
||||
SIGRefType:
|
||||
ActivityRefType:
|
||||
type: string
|
||||
enum:
|
||||
- PARK
|
||||
@@ -1075,26 +1075,26 @@ components:
|
||||
- NONE
|
||||
example: "HOME QTH"
|
||||
|
||||
SIGRef:
|
||||
ActivityRef:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: SIG reference ID.
|
||||
description: Activity reference ID.
|
||||
example: GB-0001
|
||||
sig:
|
||||
description: SIG that this reference is in.
|
||||
$ref: "#/components/schemas/SIGName"
|
||||
description: Activity that this reference is in. Still named "sig" in the API for backwards compatibility.
|
||||
$ref: "#/components/schemas/ActivityName"
|
||||
name:
|
||||
type: string
|
||||
description: SIG reference name
|
||||
description: Activity reference name
|
||||
example: Null Country Park
|
||||
ref_type:
|
||||
description: SIG reference type
|
||||
$ref: "#/components/schemas/SIGRefType"
|
||||
description: Activity reference type
|
||||
$ref: "#/components/schemas/ActivityRefType"
|
||||
url:
|
||||
type: string
|
||||
description: SIG reference URL, which the user can look up for more information
|
||||
description: Activity reference URL, which the user can look up for more information
|
||||
example: "https://pota.app/#/park/GB-0001"
|
||||
grid:
|
||||
type: string
|
||||
@@ -1136,7 +1136,7 @@ components:
|
||||
dx_qth:
|
||||
type: string
|
||||
description: >
|
||||
QTH of the operator that has been spotted. This could be from any SIG refs or could be
|
||||
QTH of the operator that has been spotted. This could be from any activity refs or could be
|
||||
from online lookup of their home QTH.
|
||||
example: Dorset
|
||||
dx_country:
|
||||
@@ -1194,7 +1194,7 @@ components:
|
||||
dx_location_source:
|
||||
description: >
|
||||
Where we got the DX location (grid/latitude/longitude) from. If this was from the spot
|
||||
itself, or from a lookup of the SIG ref (e.g. park) it's likely quite accurate, but if
|
||||
itself, or from a lookup of the activity ref (e.g. park) it's likely quite accurate, but if
|
||||
we had to fall back to QRZ lookup, or even a location based on the DXCC itself, it will
|
||||
be a lot less accurate. "SPOT" indicates the location source was the spot itself from the
|
||||
spotting service. "SIG REF LOOKUP" indicates that the spot didn't provide a location,
|
||||
@@ -1308,13 +1308,13 @@ components:
|
||||
description: Comment left by the spotter, if any
|
||||
example: "59 in NY 73"
|
||||
sig:
|
||||
description: Special Interest Group (SIG), e.g. outdoor activity programme such as POTA
|
||||
$ref: "#/components/schemas/SIGName"
|
||||
description: Activity, e.g. outdoor activity programme such as POTA (still named "sig" in the API for backwards compatibility)
|
||||
$ref: "#/components/schemas/ActivityName"
|
||||
sig_refs:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/SIGRef'
|
||||
description: SIG references. We allow multiple here for e.g. n-fer activations, unlike ADIF SIG_INFO
|
||||
$ref: '#/components/schemas/ActivityRef'
|
||||
description: Activity references. We allow multiple here for e.g. n-fer activations, unlike ADIF SIG_INFO. Still named "sig_refs" in the API for backwards compatibility.
|
||||
qrt:
|
||||
type: boolean
|
||||
description: QRT state. Some APIs return spots marked as QRT. Otherwise we can check the comments.
|
||||
@@ -1358,13 +1358,13 @@ components:
|
||||
If true, forward the spot to an external upstream provider (e.g. POTA, SOTA) rather
|
||||
than only adding it to this Spothole server. Requires `sig`, at least one `sig_refs`
|
||||
entry, and `upstream_provider` to be set. Check `spot_submit_providers` in the
|
||||
/options response to see which SIGs and providers support this.
|
||||
/options response to see which activities and providers support this.
|
||||
default: false
|
||||
upstream_provider:
|
||||
type: string
|
||||
description: >
|
||||
Name of the upstream provider to submit the spot to, e.g. "POTA" or "SOTA". Must
|
||||
match one of the provider names returned in `spot_submit_providers` for the chosen SIG.
|
||||
match one of the provider names returned in `spot_submit_providers` for the chosen activity.
|
||||
example: POTA
|
||||
upstream_credentials:
|
||||
type: object
|
||||
@@ -1481,13 +1481,13 @@ components:
|
||||
description: Comment made by the activator, if any
|
||||
example: "2025 DXpedition to null island"
|
||||
sig:
|
||||
description: Special Interest Group (SIG), e.g. outdoor activity programme such as POTA
|
||||
$ref: "#/components/schemas/SIGName"
|
||||
description: Activity, e.g. outdoor activity programme such as POTA (still named "sig" in the API for backwards compatibility)
|
||||
$ref: "#/components/schemas/ActivityName"
|
||||
sig_refs:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/SIGRef'
|
||||
description: SIG references. We allow multiple here for e.g. n-fer activations, unlike ADIF SIG_INFO
|
||||
$ref: '#/components/schemas/ActivityRef'
|
||||
description: Activity references. We allow multiple here for e.g. n-fer activations, unlike ADIF SIG_INFO. Still named "sig_refs" in the API for backwards compatibility.
|
||||
alert_type:
|
||||
description: "The type of alert this is: xOTA, DXpedition, or Contest."
|
||||
$ref: "#/components/schemas/AlertType"
|
||||
@@ -1581,28 +1581,32 @@ components:
|
||||
description: The end frequency of this band, in Hz.
|
||||
example: 7200000
|
||||
|
||||
SIG:
|
||||
Activity:
|
||||
type: object
|
||||
description: >
|
||||
Represents an activity (a term which replaces the older "Special Interest Group" or "SIG" terminology,
|
||||
though `sig`-prefixed field names remain for API backwards compatibility).
|
||||
properties:
|
||||
name:
|
||||
description: The abbreviated name of the SIG
|
||||
$ref: "#/components/schemas/SIGName"
|
||||
description: The abbreviated name of the activity
|
||||
$ref: "#/components/schemas/ActivityName"
|
||||
description:
|
||||
type: string
|
||||
description: The full name of the SIG
|
||||
description: The full name of the activity
|
||||
example: Parks on the Air
|
||||
sig_type:
|
||||
type: boolean
|
||||
description: >
|
||||
Whether the SIG is worldwide, regional, or for a specific event. Generally for Spothole's own internal use,
|
||||
clients probably won't need this. Used to group them in the web UI.
|
||||
$ref: "#/components/schemas/SIGType"
|
||||
Whether the activity is worldwide, regional, or for a specific event. Generally for Spothole's own
|
||||
internal use, clients probably won't need this. Used to group them in the web UI. Still named
|
||||
"sig_type" in the API for backwards compatibility.
|
||||
$ref: "#/components/schemas/ActivityType"
|
||||
comment_names:
|
||||
type: array
|
||||
description: >
|
||||
Names by which this SIG may be referred to in cluster spot comments. Most SIGs have a
|
||||
Names by which this activity may be referred to in cluster spot comments. Most activities have a
|
||||
single entry matching their programme name (e.g. ["POTA"]), but some have none (where
|
||||
the name is ambiguous with other SIGs, such as Tiles and Toilets on the Air) or multiple
|
||||
the name is ambiguous with other activities, such as Tiles and Toilets on the Air) or multiple
|
||||
entries (e.g. WWBOTA accepts both "WWBOTA" and "BOTA" since the latter is often used).
|
||||
items:
|
||||
type: string
|
||||
@@ -1610,26 +1614,27 @@ components:
|
||||
ref_regex:
|
||||
type: string
|
||||
description: >
|
||||
Regex that matches this SIG's reference IDs. Generally for Spothole's own internal use,
|
||||
Regex that matches this activity's reference IDs. Generally for Spothole's own internal use,
|
||||
clients probably won't need this.
|
||||
example: "[A-Z]{2}\\-\\d+"
|
||||
refs_globally_unique:
|
||||
type: boolean
|
||||
description: >
|
||||
Identifies that the SIG's reference ID structure defined by its regex is unique across all programmes and
|
||||
anything else we expect a user to put in a spot comment, and therefore we can pull references out of
|
||||
spot comments without also needing to see the SIG name first. For example, "OHFF-1234" or "B/G-1234" are
|
||||
obviously WWFF and WWBOTA, nothing else looks like those. But "SZ09" could be WAB or Tiles, "GB1234" could
|
||||
conceivably be POTA or ILLW, etc. Generally for Spothole's own internal use, clients probably won't need
|
||||
this.
|
||||
Identifies that the activity's reference ID structure defined by its regex is unique across all
|
||||
programmes and anything else we expect a user to put in a spot comment, and therefore we can pull
|
||||
references out of spot comments without also needing to see the activity name first. For example,
|
||||
"OHFF-1234" or "B/G-1234" are obviously WWFF and WWBOTA, nothing else looks like those. But "SZ09"
|
||||
could be WAB or Tiles, "GB1234" could conceivably be POTA or ILLW, etc. Generally for Spothole's own
|
||||
internal use, clients probably won't need this.
|
||||
icon:
|
||||
type: string
|
||||
description: Icon from the Font Awesome set that represents this SIG, for use in the front end.
|
||||
description: Icon from the Font Awesome set that represents this activity, for use in the front end.
|
||||
example: "fa-tree"
|
||||
region_flag:
|
||||
type: string
|
||||
description: >
|
||||
Flag emoji, if this SIG is specific to a country or region. If null, this SIG is treated as worldwide.
|
||||
Flag emoji, if this activity is specific to a country or region. If null, this activity is treated as
|
||||
worldwide.
|
||||
example: "🇺🇳"
|
||||
|
||||
SolarConditions:
|
||||
@@ -1978,12 +1983,12 @@ components:
|
||||
is zero, the provider has never updated.
|
||||
example: 1759579508
|
||||
|
||||
SIGRefDataProviderStatus:
|
||||
ActivityRefDataProviderStatus:
|
||||
type: object
|
||||
properties:
|
||||
sig_name:
|
||||
type: string
|
||||
description: The name of the SIG.
|
||||
description: The name of the activity. Still named "sig_name" in the API for backwards compatibility.
|
||||
example: WWFF
|
||||
enabled:
|
||||
type: boolean
|
||||
@@ -2148,9 +2153,9 @@ components:
|
||||
$ref: '#/components/schemas/StaticDataProviderStatus'
|
||||
sig_ref_data_providers:
|
||||
type: array
|
||||
description: An array of all the SIG reference data providers.
|
||||
description: An array of all the activity reference data providers.
|
||||
items:
|
||||
$ref: '#/components/schemas/SIGRefDataProviderStatus'
|
||||
$ref: '#/components/schemas/ActivityRefDataProviderStatus'
|
||||
callsign_data_providers:
|
||||
type: array
|
||||
description: An array of all the callsign data providers.
|
||||
@@ -2179,9 +2184,9 @@ components:
|
||||
example: "PHONE"
|
||||
sigs:
|
||||
type: array
|
||||
description: An array of all the supported Special Interest Groups.
|
||||
description: An array of all the supported activities.
|
||||
items:
|
||||
$ref: '#/components/schemas/SIG'
|
||||
$ref: '#/components/schemas/Activity'
|
||||
spot_providers:
|
||||
type: array
|
||||
description: An array of all the supported spot data sources.
|
||||
@@ -2228,9 +2233,9 @@ components:
|
||||
spot_submit_providers:
|
||||
type: object
|
||||
description: >
|
||||
A map of SIG name to a list of provider names that support upstream spot submission for that SIG.
|
||||
If a SIG appears as a key here, the POST /spot endpoint accepts `submit_upstream: true` for
|
||||
spots with that SIG, and will forward the spot to one of the listed providers. Omitted if no
|
||||
A map of activity name to a list of provider names that support upstream spot submission for that
|
||||
activity. If an activity appears as a key here, the POST /spot endpoint accepts `submit_upstream: true`
|
||||
for spots with that activity, and will forward the spot to one of the listed providers. Omitted if no
|
||||
providers support upstream submission.
|
||||
additionalProperties:
|
||||
type: array
|
||||
@@ -2258,7 +2263,7 @@ components:
|
||||
qth:
|
||||
type: string
|
||||
description: >
|
||||
QTH of the operator. This could be from any SIG refs or could be from online lookup of
|
||||
QTH of the operator. This could be from any activity refs or could be from online lookup of
|
||||
their home QTH.
|
||||
example: Dorset
|
||||
country:
|
||||
|
||||
Reference in New Issue
Block a user