--- title: "Human Design Extended Placements" method: POST path: "/human-design/extended" tags: ["Human Design"] --- # Human Design Extended Placements `POST /human-design/extended` ## Request - Base URL: `https://api.openephemeris.com` - URL: `https://api.openephemeris.com/human-design/extended` - 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` Human Design address for points beyond the 13 bodygraph bodies, at the Personality instant and at the Design instant (88° of solar arc earlier), both at the birth location. Choose what to compute with `include`: `bodies` (asteroids, Chiron, Lilith, Vertex, the mean node and the Uranian set), `angles` (ASC, DSC, MC, IC), `lots` (the seven Hermetic Lots, cast in the sect of each instant's own chart — Sun above the horizon is a day chart), `stars` (fixed stars, evaluated at each epoch) and `kernel_bodies` (opt-in: the kernel-backed catalog of asteroids, centaurs and trans-Neptunian objects, named as on the /acg endpoints; a requested body whose kernel does not cover the Personality or Design instant refuses the whole request with a 422). `bodies` alone is the default. Stars need `star_groups` (see `GET /catalogs/fixed-stars/groups`), `star_names` (catalog slugs, see `GET /catalogs/fixed-stars`), or both; the result is their union, de-duplicated and in catalog order. These points never enter the bodygraph: no definition, channels, centers, type, authority or cross. Use `/human-design/chart` for those. **Access:** any API key can call this route. Every key receives `gate` and `line` for each point. `longitude`, `color`, `tone` and `base` (and a star's ecliptic `latitude`) are returned only on Pro plans and above; on other keys they are omitted and `metadata.deep_fields` is `false`. **Pricing:** priced by what you ask for, once per request (Personality and Design together): extended bodies 3 credits, angles 1, Hermetic Lots 2, fixed stars 3 per star group plus 1 per named star (capped at 20), kernel bodies 1 per named body capped at 20 (naming none costs 20). The smallest request (angles only) is 1 credit. The price is read from the request before any compute, and a rejected request is refunded. ## Request body - HumanDesignExtendedRequest: Request for extended Human Design placements. Exactly one of `birth_datetime_utc` (an instant) or `birth_datetime_local` (a naive local wall-clock time the server converts using the birth coordinates and the historical-correction overlay) is required, as on `/human-design/chart`. `latitude` and `longitude` are both required (an omitted one is a 422, never defaulted to 0,0): the Vertex, the angles and the Hermetic Lots all depend on the birthplace. - `birth_datetime_local` string: Naive local wall-clock birth datetime (YYYY-MM-DDTHH:MM:SS, no zone suffix), resolved by the server. Mutually exclusive with `birth_datetime_utc`. - `birth_datetime_utc` string, date-time: Birth instant as an RFC 3339 datetime, e.g. '1987-07-15T14:01:00Z'. Mutually exclusive with `birth_datetime_local`. - `bodies` string[]: Extended bodies to return, by name (case-insensitive). Omit for the whole extended roster. Only valid when `include` contains `bodies`. An unknown name is rejected and the valid names are listed. - `include` string[]: Components to compute: `bodies`, `angles`, `lots`, `stars`, `kernel_bodies`. Each is priced separately. `kernel_bodies` is opt-in: the kernel-backed catalog (asteroids, centaurs and trans-Neptunian objects beyond the `bodies` roster, as named on the /acg endpoints, e.g. `Eros (asteroid)`); it is never included unless asked for. - `kernel_bodies` string[]: Kernel-catalog bodies to return, by ACG name (case-insensitive), e.g. `Eris`, `Eros (asteroid)`. Omit for the whole kernel catalog. Only valid when `include` contains `kernel_bodies`. An unknown name is rejected and the valid names are listed. Priced 1 credit per distinct body, capped at 20 (naming none costs the cap). Bodies with their own kernel cover 1600 to 2200 CE (the rest 1550 to 2650 CE); a birth whose Personality or Design instant falls outside a requested body's window is refused with a 422, never approximated. The Design instant is about 88 days before birth. - `latitude` number, double: Birth latitude in decimal degrees, within [-90, 90]. Required. - `longitude` number, double: Birth longitude in decimal degrees, within [-180, 180]. Required. - `star_groups` string[]: Fixed-star groups to return (names from `GET /catalogs/fixed-stars/groups`). Only valid when `include` contains `stars`, which needs `star_groups`, `star_names` or both. Priced per distinct group. - `star_names` string[]: Fixed stars to return by catalog slug (case-insensitive; spaces read as underscores), e.g. `rigil_kentaurus`, `rasalhague`, `elnath`, `altair`. Slugs are listed at `GET /catalogs/fixed-stars`. Only valid when `include` contains `stars`. May be combined with `star_groups`: the result is the union, de-duplicated and in catalog order. An unknown slug is rejected with a 422 that lists the valid slugs. Priced 1 credit per distinct name, capped at 20. - `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 ## Response `200` Successful Response - HumanDesignExtendedResponse: Extended placements at the Personality and Design instants. - `design` HumanDesignExtendedItem[], required - `base` integer: Base 1-5. Pro plans and above. - `color` integer: Color 1-6. Pro plans and above. - `gate` integer, required: Gate 1-64. - `id` string, required: Body name (e.g. `Chiron`), angle (`ASC`, `DSC`, `MC`, `IC`), lot (`lot_of_fortune` …) or star slug. - `kind` string, required: One of `body`, `angle`, `lot`, `star`. - `latitude` number, double: Ecliptic latitude in degrees, for `star` items only. Pro plans and above. - `line` integer, required: Line 1-6. - `longitude` number, double: Tropical ecliptic longitude in degrees. Pro plans and above. - `tone` integer: Tone 1-6. Pro plans and above. - `metadata` object, required: `natal_jd`, `design_jd`, `deep_fields` (whether longitude/color/tone/base are included) and, when they are not, `deep_fields_note`. - `personality` HumanDesignExtendedItem[], required - `base` integer: Base 1-5. Pro plans and above. - `color` integer: Color 1-6. Pro plans and above. - `gate` integer, required: Gate 1-64. - `id` string, required: Body name (e.g. `Chiron`), angle (`ASC`, `DSC`, `MC`, `IC`), lot (`lot_of_fortune` …) or star slug. - `kind` string, required: One of `body`, `angle`, `lot`, `star`. - `latitude` number, double: Ecliptic latitude in degrees, for `star` items only. Pro plans and above. - `line` integer, required: Line 1-6. - `longitude` number, double: Tropical ecliptic longitude in degrees. Pro plans and above. - `tone` integer: Tone 1-6. Pro plans and above. ## Other responses - `422`: Validation 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)