astrology-location-time-utc

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

Primary Astro Engine app:

https://astro-engine.apps.poofc.com

Legacy compatible URL, still useful when checking older integrations:

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:

• timezone — resolved IANA timezone
• localISO — interpreted local time
• utcISO — correct UTC instant
• utcDate — transit-list-demo string to pass as natal, transit, or utc
• location.latitude / location.longitude for house calculations

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:

• getTimezoneFromGoogle(...)
• DateTime.local(..., { zone: timezone })
• dateTimeLocal.toMillis() / toUTC()

Deployment / maintenance notes

The deployed service is now Astro Engine:

Path: /home/avalon/apps/astro-engine
PM2: astro-engine
Port: 4021
Primary public URL: https://astro-engine.apps.poofc.com
Legacy compatible 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/astro-engine
npm test
node --check server.js
PORT=4021 pm2 restart astro-engine --update-env
curl -ks https://astro-engine.apps.poofc.com/api/health
curl -ks 'https://astro-engine.apps.poofc.com/api/time/resolve?date=1985-09-26&time=07:14&location=London,%20England'
curl -ks 'https://astro-engine.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.

Browser/app UX patterns

When building chart UI controls on Astro Engine:

• See references/astro-engine-browser-location-controls.md for the concrete browser-date/time + houses fix pattern.
• Never submit /api/time/resolve with blank date or time. Initialize controls from the browser/device first:
• new Date() for local date/time fields.
• Intl.DateTimeFormat().resolvedOptions().timeZone for the default IANA timezone.
• Provide a "Use browser now" affordance so a user can quickly load the current device date/time.
• Provide a "Use device location" affordance via navigator.geolocation when the browser permits it; use the resulting latitude longitude directly as chart coordinates.
• If a named place is entered, send location= to Astro Engine so the server-side Google geocoding/timezone credentials remain server-side.
• If both a named location and a browser timezone are available, prefer resolving from location for astrology charts so coordinates are returned for houses. Browser timezone alone is acceptable for UTC conversion but not for houses.
• After resolving a location, render chart SVGs with coordinates=LAT%20LON or location=LAT%20LON plus houses=P so house cusps appear.

Pitfalls

• Do not use the server's local timezone.
• Do not assume a fixed offset like -8 for Los Angeles; DST changes.
• Do not use the current timezone offset for historical dates. Resolve timezone for the chart date.
• If the user provides an IANA timezone directly, it can be used instead of geocoding.
• transit-list-demo uses day-first dates, not US month/day order.
• For astrology houses, location coordinates are required; timezone alone is not enough.
• In JavaScript browser code, guard coordinate values with value != null before Number.isFinite(Number(value)). Number(null) is 0, so nullable chart rows can otherwise become the bogus coordinate string null null and trigger invalid location errors.
• Always commit and push transit-list-demo/Astro Engine server/package changes after deploy.