w1cdn/spothole
1
0
Fork 0
mirror of https://git.ianrenton.com/ian/spothole.git synced 2026-09-25 08:44:33 +00:00
Code Issues 13 Packages Projects Releases Wiki Activity

sig->activity and multiple activity changes for API v3. #143

Browse Source
This commit is contained in:
ian
2026-09-25 07:01:13 +01:00
committed by Ian Renton
parent 02d08c17cd
commit ecdcbe17e9
92 changed files with 1113 additions and 796 deletions
Download Patch File Download Diff File Expand all files Collapse all files
static/apidocs/openapi.yml
+86 -56
View File
@@ -15,6 +15,25 @@ info:
## Changelog
### 3.0
The term "SIG" (Special Interest Group), which Spothole inherited from ADIF, has been replaced with "activity" throughout the API.
* **Breaking change:** In spot and alert data, the single `sig` value has been replaced with `activities`, a list of unique activity names. A spot or alert can now be associated with more than one activity (e.g. a POTA and WWFF dual activation, a /MM activation via satellite, etc). The array is empty if there is no associated activity. `sig_refs` has been renamed to `activity_refs`.
* **Breaking change:** In activity reference data (i.e. each entry in `activity_refs` of a spot or alert, and the response of the activity reference lookup), `sig` has been renamed to `activity`.
* **Breaking change:** The `dx_location_source` value "SIG REF LOOKUP" has been renamed to "ACTIVITY REF LOOKUP".
* **Breaking change:** The `/spots`, `/spots/stream`, `/alerts` and `/alerts/stream` query parameter `sig` has been renamed to `activity`, and its special value `NO_SIG` to `NO_ACTIVITY`. The `/spots` and `/spots/stream` query parameters `needs_sig` and `needs_sig_ref` have been renamed to `needs_activity` and `needs_activity_ref`. The `activity` filter now matches any spot or alert that has at least one of the requested activities.
* **Breaking change:** `/lookup/sigref` has been renamed to `/lookup/activityref`, and its `sig` query parameter has been renamed to `activity`.
* **Breaking change:** POST `/spot` now expects `activities` (a list) and `activity_refs` in the `spot` object, rather than `sig` and `sig_refs`.
* **Breaking change:** In the `/options` response, `sigs` has been renamed to `activities`, and within each activity, `sig_type` has been renamed to `activity_type`.
* **Breaking change:** In the `/status` response, `sig_ref_data_providers` has been renamed to `activity_ref_data_providers`, and within each provider, `sig_name` has been renamed to `activity_name`.
#### Upgrading a client from v2 to v3 API endpoints
In v3.0 of Spothole, the `v2` (and `v1`) API endpoints will be maintained for backwards compatibility, so if you have written a client against the `v2` API, it will continue to receive `sig`, `sig_refs` etc. as before. Where a spot or alert has more than one activity, the `v2` and `v1` APIs will return only the first one as `sig`.
You are encouraged to move to the `v3` API endpoints as soon as possible. To upgrade, replace `v2` with `v3` in the URLs your code calls, then rename any use of the fields, query parameters and values listed above, and handle `activities` being a list rather than a single `sig` value. If you use the activity reference lookup, call `/lookup/activityref?activity=...&id=...` instead of `/lookup/sigref?sig=...&id=...`.
### 2.2
* Renamed AMSAT SIG to "Satellite" as AMSAT is a specific organisation not just a general term for satellite QSOs
@@ -102,10 +121,10 @@ info:
license:
name: The Unlicense
url: https://unlicense.org/#the-unlicense
version: 2.0
version: 3.0
servers:
- url: https://spothole.app/api/v2
- url: https://spothole.app/api/v3
tags:
- name: Spots
@@ -396,7 +415,7 @@ paths:
example: "Failed"
/lookup/sigref:
/lookup/activityref:
get:
tags:
- Utilities
@@ -405,7 +424,7 @@ paths:
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
operationId: activityref
parameters:
- $ref: '#/components/parameters/ActivityRefLookupActivity'
- $ref: '#/components/parameters/ActivityRefLookupId'
@@ -461,7 +480,7 @@ paths:
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 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`"
`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/v3/spot`"
operationId: spot
requestBody:
description: Object containing a "spot" sub-object with the spot data, and an optional "handling" sub-object with server-side instructions of what to do with it.
@@ -559,32 +578,32 @@ components:
schema:
$ref: "#/components/schemas/Source"
SpotActivity:
name: sig
name: activity
in: query
description: >
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.
To select more than one activity, supply a comma-separated list. A spot matches if any of its activities are
in the list. The special `activity` name `NO_ACTIVITY` matches spots with no activity set. You can use
`activity=NO_ACTIVITY` 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 but not No Activity', see the `needs_activity` query parameter for a shortcut.
schema:
$ref: "#/components/schemas/ActivityNameIncludingNoSig"
$ref: "#/components/schemas/ActivityNameIncludingNoActivity"
SpotNeedsActivity:
name: needs_sig
name: needs_activity
in: query
description: >
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
known activities as an `activity` parameter is unwieldy, and leaving `activity` 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 activity apart from the special `NO_SIG` value. This is what Field
what it is, so long as it's not blank. This is the equivalent of supplying the `activity` query
param with a list of every known activity apart from the special `NO_ACTIVITY` value. This is what Field
Spotter uses to exclude generic cluster spots and only retrieve xOTA things.
schema:
type: boolean
default: false
SpotNeedsActivityRef:
name: needs_sig_ref
name: needs_activity_ref
in: query
description: >
Limit the spots to only ones which have at least one reference (e.g. a park reference) for
@@ -723,14 +742,13 @@ components:
schema:
$ref: "#/components/schemas/Source"
AlertActivity:
name: sig
name: activity
in: query
description: >
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).
activity, supply a comma-separated list. An alert matches if any of its activities are in the list.
schema:
$ref: "#/components/schemas/ActivityNameIncludingNoSig"
$ref: "#/components/schemas/ActivityNameIncludingNoActivity"
AlertDxContinent:
name: dx_continent
in: query
@@ -839,9 +857,9 @@ components:
type: string
example: M0TRT
ActivityRefLookupActivity:
name: sig
name: activity
in: query
description: Activity, e.g. outdoor activity programme such as POTA (still named "sig" in the API for backwards compatibility)
description: Activity, e.g. outdoor activity programme such as POTA
required: true
schema:
$ref: "#/components/schemas/ActivityName"
@@ -938,11 +956,11 @@ components:
- EVENT
example: TRADITIONAL
ActivityNameIncludingNoSig:
ActivityNameIncludingNoActivity:
oneOf:
- $ref: "#/components/schemas/ActivityName"
- type: string
enum: [ NO_SIG ]
enum: [ NO_ACTIVITY ]
example: POTA
ActivityRefType:
@@ -1068,7 +1086,7 @@ components:
type: string
enum:
- SPOT
- "SIG REF LOOKUP"
- "ACTIVITY REF LOOKUP"
- "GRID"
- "HOME QTH"
- DXCC
@@ -1090,8 +1108,8 @@ components:
type: string
description: Activity reference ID.
example: GB-0001
sig:
description: Activity that this reference is in. Still named "sig" in the API for backwards compatibility.
activity:
description: Activity that this reference is in.
$ref: "#/components/schemas/ActivityName"
name:
type: string
@@ -1205,7 +1223,7 @@ components:
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,
spotting service. "ACTIVITY REF LOOKUP" indicates that the spot didn't provide a location,
but we looked it up from reference data. "GRID" indicates that the spot provided some
location data such as a Maidenhead, UK Ordnance Survey or Irish grid reference, but the
location is likely less accurate than "SPOT". "HOME QTH" indicates we looked up the DX
@@ -1218,7 +1236,7 @@ components:
type: boolean
description: >
Does the software think the location is good enough to put a marker on a map? This is
true if the source is "SPOT", "SIG REF LOOKUP" or "GRID", or alternatively if
true if the source is "SPOT", "ACTIVITY REF LOOKUP" or "GRID", or alternatively if
the source is "HOME QTH" and the callsign doesn't have a slash in it (i.e. operator
likely at home).
example: true
@@ -1315,14 +1333,21 @@ components:
type: string
description: Comment left by the spotter, if any
example: "59 in NY 73"
sig:
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:
activities:
type: array
uniqueItems: true
items:
$ref: "#/components/schemas/ActivityName"
description: >
Activities, e.g. outdoor activity programmes such as POTA. There may be more than one, e.g. for a POTA plus
WWFF dual activation, or none. Each activity appears at most once. The first activity is the "primary" one,
e.g. the activity of the programme the spot came from, and is the one used to choose the icon.
example: [ "POTA", "WWFF" ]
activity_refs:
type: array
items:
$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.
description: Activity references. We allow multiple here for e.g. n-fer activations, unlike ADIF SIG_INFO.
qrt:
type: boolean
description: QRT state. Some APIs return spots marked as QRT. Otherwise we can check the comments.
@@ -1363,10 +1388,9 @@ components:
submit_upstream:
type: boolean
description: >
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 activities and providers support this.
If true, forward the spot to an external upstream provider (e.g. POTA, SOTA) rather than only adding it
to this Spothole server. Requires `upstream_provider` to be set. Check `spot_submit_providers` in the
`/options` response to see which activities and providers support this.
default: false
upstream_provider:
type: string
@@ -1503,14 +1527,21 @@ components:
type: string
description: Comment made by the activator, if any
example: "2025 DXpedition to null island"
sig:
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:
activities:
type: array
uniqueItems: true
items:
$ref: "#/components/schemas/ActivityName"
description: >
Activities, e.g. outdoor activity programmes such as POTA. There may be more than one, e.g. for a POTA and
WWFF dual activation, or none. Each activity appears at most once. The first activity is the "primary" one,
e.g. the activity of the programme the spot came from, and is the one used to choose the icon.
example: [ "POTA", "WWFF" ]
activity_refs:
type: array
items:
$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.
description: Activity references. We allow multiple here for e.g. n-fer activations, unlike ADIF SIG_INFO.
url:
type: string
description: A URL linking to more information about the alert, e.g. DXpedition or contest info.
@@ -1604,8 +1635,8 @@ components:
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).
Represents an activity, such as an outdoor activity programme (e.g. POTA), or another kind of operating
(e.g. Contest, DXpedition).
properties:
name:
description: The abbreviated name of the activity
@@ -1614,12 +1645,11 @@ components:
type: string
description: The full name of the activity
example: Parks on the Air
sig_type:
type: boolean
activity_type:
description: >
Whether the activity is traditional (e.g. EME), adventure (e.g. POTA), regional (e.g. WAB), or for a
specific event (e.g. MOTA). 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.
Used to group them in the web UI.
$ref: "#/components/schemas/ActivityType"
has_refs:
type: boolean
@@ -1998,7 +2028,7 @@ components:
StaticDataProviderStatus:
type: object
properties:
sig_name:
name:
type: string
description: The name of the provider.
example: K0SWE
@@ -2020,9 +2050,9 @@ components:
ActivityRefDataProviderStatus:
type: object
properties:
sig_name:
activity_name:
type: string
description: The name of the activity. Still named "sig_name" in the API for backwards compatibility.
description: The name of the activity.
example: WWFF
enabled:
type: boolean
@@ -2046,7 +2076,7 @@ components:
CallsignDataProviderStatus:
type: object
properties:
sig_name:
name:
type: string
description: The name of the provider.
example: Country Files
@@ -2185,7 +2215,7 @@ components:
description: An array of all the static reference data providers.
items:
$ref: '#/components/schemas/StaticDataProviderStatus'
sig_ref_data_providers:
activity_ref_data_providers:
type: array
description: An array of all the activity reference data providers.
items:
@@ -2216,7 +2246,7 @@ components:
items:
type: string
example: "PHONE"
sigs:
activities:
type: array
description: An array of all the supported activities.
items:
@@ -2254,7 +2284,7 @@ components:
type: integer
description: >
The maximum age, in seconds, of any spot before it will be deleted by the system. When
querying the /api/v2/spots endpoint and providing a "max_age" or "since" parameter, there
querying the /api/v3/spots endpoint and providing a "max_age" or "since" parameter, there
is no point providing a number larger than this, because the system drops all spots older
than this.
example: 3600