Omni API

Weather, time, Docker status, and email endpoints in one service. The weather watchlist can now be updated at runtime, so clients can add a new location like Hollis Center, ME without redeploying the app.

Weather watches refresh every REFRESH_INTERVAL_MS (default 600000 ms / 10 minutes).

Weather Watch Logic

The API keeps a watchlist of locations. Every watched location is refreshed automatically on the server's background timer.

REFRESH_INTERVAL_MS controls the background refresh cadence. Default: 600000 ms (10 minutes).
Normal single-location reads reuse weather data for 5 seconds, while GET /weather/fresh/:id bypasses that debounce window.
Locations added through the new watchlist endpoint are available immediately and can also be persisted to disk.

Endpoints

GET

/time

Returns the current server time.

GET

/weather/all

Returns a summary for every watched location.

GET

/weather/watchlist

Returns the watched locations plus refresh settings.

{
  "refreshIntervalMs": 600000,
  "freshDebounceMs": 5000,
  "locations": [
    { "id": 0, "location": "Portland, ME" },
    { "id": 1, "location": "Wallkill, NY" }
  ]
}

POST

/weather/watchlist

Adds a new watched location and fetches it right away.

{
  "location": "Hollis Center, ME"
}

GET

/weather/:id

Returns the full forecast payload for one watched location.

GET

/weather/fresh/:id

Forces an immediate fresh weather lookup for one watched location.

GET

/docker/liststate

Lists the host Docker containers when the Docker socket is mounted into the container.

POST

/sendemail

Sends or schedules an email. Requires the existing auth header for your deployment.

Add A New Watched Location

Example: tell the API to start watching Hollis Center, ME.

cURL

curl -X POST http://localhost:3000/weather/watchlist \
  -H "Content-Type: application/json" \
  -d "{\"location\":\"Hollis Center, ME\"}"

PowerShell

Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:3000/weather/watchlist" `
  -ContentType "application/json" `
  -Body '{"location":"Hollis Center, ME"}'

Example Response

{
  "added": true,
  "persisted": true,
  "id": 2,
  "location": "Hollis Center, ME",
  "refreshIntervalMs": 600000,
  "freshDebounceMs": 5000,
  "data": {
    "location": { "...": "..." },
    "current": { "...": "..." }
  }
}

Configuration

Create a local .env file on the server. Keep the WeatherAPI key there, not in the public docs page.

PORT=3000
WEATHER_API_KEY=your_weatherapi_key
WEATHER_LOCATIONS=Portland, ME|Wallkill, NY
REFRESH_INTERVAL_MS=600000
WEATHER_LOCATIONS_FILE=/usr/src/app/data/weather-locations.json

The docs page intentionally uses placeholders. Put the real WEATHER_API_KEY only in .env or an --env-file, never directly into the public HTML page.

Docker Deployment

1. Build or pull the image

docker pull dss.lndotech.com/omni-api:0.0.32

2. Run it with a secure env file and persistent watchlist storage

docker run -d \
  --name omni-api \
  --user root \
  -p 10045:3000 \
  -v omni-api-data:/usr/src/app/data \
  -v //var/run/docker.sock:/var/run/docker.sock \
  --env-file .env \
  -e DOCKER_SOCKET=/var/run/docker.sock \
  --restart unless-stopped \
  dss.lndotech.com/omni-api:0.0.32

If you do not need /docker/liststate, omit --user root, the Docker socket mount, and DOCKER_SOCKET.

3. Verify

curl http://localhost:10045/weather/watchlist
curl http://localhost:10045/weather/all