From 732ea61a2efa3ce2a47d4c78277caa226c4549c4 Mon Sep 17 00:00:00 2001 From: Graham McIntire Date: Sun, 22 Mar 2026 12:16:21 -0500 Subject: [PATCH] docs: add weather nearby API endpoint to documentation Adds comprehensive documentation for GET /api/v1/weather/nearby endpoint: - Parameter descriptions (lat, lon, radius, hours, limit) - Example requests with curl - Success and error response formats - Updated planned endpoints section --- lib/aprsme_web/live/api_docs_live.ex | 187 ++++++++++++++++++++++++++- 1 file changed, 186 insertions(+), 1 deletion(-) diff --git a/lib/aprsme_web/live/api_docs_live.ex b/lib/aprsme_web/live/api_docs_live.ex index dc2510b..4850c1a 100644 --- a/lib/aprsme_web/live/api_docs_live.ex +++ b/lib/aprsme_web/live/api_docs_live.ex @@ -420,6 +420,189 @@ defmodule AprsmeWeb.ApiDocsLive do + +
+
+
+

Find Nearby Weather Stations

+ + GET + +
+ +
+

Endpoint

+
+ GET /api/v1/weather/nearby +
+
+ +
+

Description

+

+ Find weather stations within a specified radius of a geographic point. Returns stations + with recent weather data, ordered by distance (closest first). Uses PostGIS spatial queries + for efficient radius filtering and deduplicates by base callsign to avoid duplicate SSIDs. +

+
+ +
+

Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription
+ lat + floatYes + Latitude of center point (-90 to 90) +
+ lon + floatYes + Longitude of center point (-180 to 180) +
+ radius + floatYes + Search radius in miles (0.0001 to 1000) +
+ hours + integerNo + Time window for recent weather data in hours (default: 6, max: 168) +
+ limit + integerNo + Maximum number of results to return (default: 50, max: 100) +
+
+
+ +
+

Example Request

+
+ 
curl -X GET "https://aprs.me/api/v1/weather/nearby?lat=37.7749&lon=-122.4194&radius=25" \
+     -H "Accept: application/json"
+
+
+ +
+

Response Format

+ +

Success Response (200 OK)

+
+ 
<%= raw ~s|{
+    "data": [
+    {
+      "callsign": "N0CALL-13",
+      "base_callsign": "N0CALL",
+      "position": {
+        "lat": 37.7849,
+        "lon": -122.4094
+      },
+      "distance_miles": 0.87,
+      "weather": {
+        "temperature": 72.5,
+        "humidity": 65.0,
+        "pressure": 1013.2,
+        "wind_speed": 8.5,
+        "wind_direction": 270,
+        "wind_gust": 12.0,
+        "rain_1h": 0.0,
+        "rain_24h": 0.5,
+        "rain_since_midnight": 0.3
+      },
+      "symbol": {
+        "table_id": "/",
+        "code": "_"
+      },
+      "comment": "Davis Vantage Pro2",
+      "last_report": "2026-03-22T15:30:00Z"
+    }
+    ],
+    "meta": {
+    "count": 1,
+    "params": {
+      "latitude": 37.7749,
+      "longitude": -122.4194,
+      "radius_miles": 25.0,
+      "hours": 6,
+      "limit": 50
+    }
+    }
+    }| %>
+
+ +

Empty Response (200 OK)

+
+ 
<%= raw ~s|{
+    "data": [],
+    "meta": {
+    "count": 0,
+    "params": {
+      "latitude": 0.0,
+      "longitude": -180.0,
+      "radius_miles": 10.0,
+      "hours": 6,
+      "limit": 50
+    }
+    }
+    }| %>
+
+ +

Error Response (400 Bad Request)

+
+ 
<%= raw ~s|{
+    "error": "Missing required parameter: lat"
+    }| %>
+
+ +

Error Response (422 Unprocessable Entity)

+
+ 
<%= raw ~s|{
+    "error": "Invalid latitude: must be a number between -90 and 90"
+    }| %>
+
+
+
+
+
@@ -624,7 +807,9 @@ defmodule AprsmeWeb.ApiDocsLive do
GET /api/v1/weather/{"{callsign}"} -

Get weather data from weather stations

+

+ Get weather history for a specific weather station +

Planned