← all skills

astrology-location-time-utc

/home/avalon/.hermes/skills/software-development/astrology-location-time-utc/SKILL.md · raw

Astrology Location/Time → UTC

Use this skill whenever Alex asks for an astrology chart/transit lookup and gives a local date/time plus location, or when an app/API expects UTC but the user speaks in local civil time.

Why this matters

transit-list-demo expects dates in UTC using this format:

day/month/fullYear/hour/minute/second

Example:

1/5/2026/3/13/0

If Alex says “April 30 2026, 8:13 PM, Los Angeles,” do not pass 30/4/2026/20/13/0 directly. Convert local Los Angeles time to the correct UTC time first, including historical DST.

Deployed API

Transit app:

https://transit-list-demo.apps.poofc.com

Useful endpoints:

GET /api/health
GET /api/transits/current
GET /api/time/resolve?date=YYYY-MM-DD&time=HH:mm[:ss]&location=LOCATION
GET /api/time/resolve?date=YYYY-MM-DD&time=HH:mm[:ss]&timezone=IANA_ZONE
GET /api/chart?date=YYYY-MM-DD&time=HH:mm[:ss]&location=LOCATION
GET /api/chart?utc=day/month/year/hour/minute/second&coordinates=LAT%20LON
GET /api/chart/svg?date=YYYY-MM-DD&time=HH:mm[:ss]&location=LOCATION

The API returns:

Required workflow

  1. Parse the user's local date and time.
  2. Parse the location.
  3. Call /api/time/resolve unless the user already gave a UTC timestamp.
  4. Use the returned utcDate for transit-list-demo calculations.
  5. If houses/Ascendant/MC are needed, pass coordinates from the resolved location.
  6. In the response, mention the resolved timezone and UTC conversion so the user can verify.

Examples

Resolve a local time

curl -s 'https://transit-list-demo.apps.poofc.com/api/time/resolve?date=2026-04-30&time=20:13&location=Los%20Angeles,%20CA'

Expected style of result:

{
  "timezone": "America/Los_Angeles",
  "localISO": "2026-04-30T20:13:00.000-07:00",
  "utcISO": "2026-05-01T03:13:00.000Z",
  "utcDate": "1/5/2026/3/13/0"
}

Get a chart from local civil time

curl -s 'https://transit-list-demo.apps.poofc.com/api/chart?date=2026-04-30&time=20:13&location=Los%20Angeles,%20CA'

Current transits

curl -s 'https://transit-list-demo.apps.poofc.com/api/transits/current'

HD Prism implementation pattern

HD Prism uses this same conceptual pattern:

  1. Geocode location with Google.
  2. Call Google Time Zone API using coordinates and a timestamp near the event.
  3. Convert local civil time in that IANA zone to UTC via Luxon.
  4. Pass UTC into the chart engine.

Important HD Prism source reference:

/home/avalon/apps/hd-prism/apps/api/src/generate-pdf-report.ts

Look around the timezone helper and Luxon conversion:

Deployment / maintenance notes

The deployed transit-list-demo process runs under PM2 on the VPS:

Path: /home/avalon/apps/transit-list-demo
PM2: transit-list-demo
Port: 4021
Public URL: https://transit-list-demo.apps.poofc.com

The production process needs a Google geocoding/timezone key in its PM2 environment. If the key is not present, /api/time/resolve with location= will fail, though timezone= can still work. The key can be sourced from the existing hd-prism-api PM2 env when deploying on Alex's VPS.

After editing the API server, verify in order:

cd /home/avalon/apps/transit-list-demo
node --check server.js
pm2 restart transit-list-demo --update-env
curl -ks https://transit-list-demo.apps.poofc.com/api/health
curl -ks 'https://transit-list-demo.apps.poofc.com/api/time/resolve?date=1985-09-26&time=07:14&location=London,%20England'
curl -ks 'https://transit-list-demo.apps.poofc.com/api/chart?date=1985-09-26&time=07:14&location=London,%20England'

When editing code that builds Google API URLs, be aware tool outputs may redact key=... fragments. Prefer constructing the key query param in a way that is easy to inspect without exposing secrets, and always run node --check server.js plus a live /api/time/resolve test before committing.

Pitfalls