---
title: "Calculate Hermetic lots for datetime and location"
method: POST
path: "/ephemeris/hermetic-lots"
tags: ["ephemeris"]
---

# Calculate Hermetic lots for datetime and location

`POST /ephemeris/hermetic-lots`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/hermetic-lots`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Calculate Hermetic lots (Fortune Suite + optional/legacy) for a given datetime and location. Returns normalized lot positions with traditional source references, formulas, and keywords. Includes sect determination (diurnal/nocturnal) and house placements. Follows standalone pattern: direct Julian Day calculation without chart context. Supports format=json|llm via query params.

## Query parameters

- `output_mode` string, nullable
- `format` string

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- HermeticLotsCalculationRequest: Request for calculating Hermetic lots (Fortune Suite + optional/legacy).
  - `date_time` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below.
    - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC.
    - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC.
    - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone)
    - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
      - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
      - `iana_name` string: IANA timezone name
      - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
      - `utc_offset` number: UTC offset in hours
  - `include_legacy` boolean: Include legacy Hermetic lots previously in canonical catalog
  - `include_optional` boolean: Include optional catalog lots beyond Fortune Suite defaults
  - `latitude` number, double, required: Observer latitude in decimal degrees
  - `longitude` number, double, required: Observer longitude in decimal degrees

## Response `200`

Successful Response

- HermeticLotsCalculationResponse: Response from Hermetic lots calculation endpoint.
  - `lots` HermeticLotResult[], required: Calculated Hermetic lots
    - `canonical_name` string, required: Internal canonical lot identifier
    - `degree_in_sign` number, double, required: Degrees within the zodiac sign (0-30)
    - `description` string: Lot meaning and interpretation
    - `display_name` string, required: Formatted display name
    - `formula` string, required: Calculation formula description
    - `house` integer: House number (1-12) if applicable
    - `keywords` string[]: Thematic keywords
    - `longitude` number, double, required: Absolute ecliptic longitude in degrees (0-360)
    - `name` string, required: Display name of the lot
    - `sign` string, required: Zodiac sign name
    - `sign_symbol` string: Unicode zodiac sign symbol
    - `traditional_source` string: Traditional source reference
  - `metadata` object, required: Calculation metadata, sect determination, and settings
  - `success` boolean: Calculation success status

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity - Invalid input format
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)