Place Search, Historical Timezones, and Deterministic Context

1. Select a place

POST /api/astro/place-search searches AstroAPI's self-hosted GeoNames cities snapshot. Results include a stable versioned place_id, display name, country, coordinates, IANA timezone, and attribution.

{
  "query": "New York",
  "country_codes": ["US"],
  "limit": 5
}

Search is deterministic for snapshot 2026-10-02. It is not address geocoding, autocomplete telemetry, or arbitrary coordinate-to-timezone polygon lookup.

2. Resolve the historical local time

POST /api/astro/timezone-resolve combines a selected place ID with a local date and clock time under IANA tzdb 2026d via tzdata 2026.4.

{
  "place_id": "geonames:5128581:2026-10-02",
  "date": "1945-08-14",
  "time": "19:00"
}

A unique civil time returns calculation_ready:true and a complete birth input. A daylight-saving fold returns both candidates; a clock gap returns no candidate. AstroAPI never selects a fold on the customer's behalf.

3. Create deterministic model-ready context

POST /api/astro/natal-context reuses the declared natal calculation and returns stable fact IDs, source paths, conventions, a calculation SHA-256, guardrails, and selected UTF-8 artifacts.

{
  "birth": {
    "date": "2000-01-01", "time": "12:00", "timezone": "UTC",
    "lat": 0, "lon": 0
  },
  "formats": ["json", "xml", "markdown"]
}

The artifacts contain calculated facts and provenance, not prompts, model instructions, predictions, medical/legal/financial advice, or an “AI astrologer.” Customers choose and govern any downstream model.

Contract and provenance limits

• Place data is GeoNames cities with population of at least 15,000 plus selected administrative seats; it is not a complete settlement or address database.
• GeoNames attribution and CC BY 4.0 metadata travel with results. The dataset and timezone release are pinned so an update is a reviewable version change.
• Pre-1970 timezone data is best-effort historical IANA data and can change between tzdb releases.
• Search and resolution are API-key-protected standard operations and use normal quota, scope, concurrency, and one-unit reservation rules.
• API keys belong only in trusted server code. Do not call these endpoints directly from an untrusted browser.