Skip to content

Well-Known Solar Time

TimeNow exposes a machine-readable discovery endpoint following RFC 8615 (Well-Known URIs).

GET /.well-known/solar-time

Returns a JSON document describing this node's solar time capabilities, supported endpoints, and current solar time.

This endpoint does not accept lat/lng query parameters. Instead, it reads the observer location from:

  1. GPS device — if a GPS receiver is connected, the daemon reads the current fix automatically.
  2. TIMENOW_GPS_COORDS environment variable — set to lat,lng (e.g., TIMENOW_GPS_COORDS=51.5,-0.1) when no GPS hardware is available.

If neither source is available, the current block is omitted from the response.

Example

# With GPS or TIMENOW_GPS_COORDS configured:
curl "http://localhost:8090/.well-known/solar-time"

Response

{
  "version": "1.0",
  "service": "timenow",
  "capabilities": ["solar", "prayer", "almanac", "ical", "mesh", "deviation-map"],
  "endpoints": {
    "solar":         "/solar",
    "prayer":        "/solar/prayer",
    "almanac":       "/solar/almanac",
    "ical":          "/solar/ical",
    "deviation_map": "/world/deviation-map",
    "mesh":          "/mesh"
  },
  "current": {
    "latitude": 51.5,
    "longitude": -0.1,
    "utc": "2026-04-14T12:00:00Z",
    "solar_time": "2026-04-14T11:49:23",
    "civil_solar_offset_min": -10.6
  }
}

RFC 8615 Compliance

The /.well-known/solar-time path follows RFC 8615 conventions:

  • Path prefix: /.well-known/
  • Content-Type: application/json
  • No authentication required
  • Stable URL that does not redirect

IANA Registration

A Well-Known URI registration for solar-time has been prepared for submission to the IANA Well-Known URI registry.

See IETF Internet-Draft for the full submission process.

Use Cases

  • Service discovery: Clients can probe /.well-known/solar-time to detect a TimeNow instance without prior knowledge of its endpoint structure.
  • Federation: Mesh nodes use this endpoint to discover peer capabilities before attempting sync.
  • Monitoring: Infrastructure monitoring tools can poll this endpoint as a comprehensive health + capability check.