---
title: "Planetary Opposition Chart"
method: POST
path: "/human-design/cycles/opposition"
tags: ["Human Design"]
---

# Planetary Opposition Chart

`POST /human-design/cycles/opposition`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/human-design/cycles/opposition`
- 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 the Human Design chart at the moment a planet opposes its natal position (180°).
Most commonly used for Uranus Opposition (~age 42), Saturn Opposition (~age 14-15, ~44), and Jupiter Opposition (~age 6, ~18, ~30).

## Request body

- AppApiRoutesHumanDesignOppositionRequest: Request for a Human Design planetary opposition chart. Exactly one of `birth_datetime_utc` (an instant the caller has already converted) or `birth_datetime_local` (a naive local wall-clock time the SERVER converts, using `latitude`/`longitude` and the historical-correction overlay) is required.
  - `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` — exactly one of the two is required. The zone comes from the sibling `timezone` field when supplied, otherwise from `latitude`/`longitude`; the historical-correction overlay is consulted for pre-1970 dates. The resolution is echoed back in the response `metadata` as tz_confidence / tz_rule_source / tz_resolved_offset / resolved_utc.
  - `birth_datetime_utc` string, date-time: Birth instant as an RFC 3339 datetime, e.g. '1987-07-15T14:01:00Z'. The caller has already done the timezone math, so the historical-correction overlay does not apply. Mutually exclusive with `birth_datetime_local`.
  - `format` string: Response format: json | llm.
  - `include_chiron` boolean: Include Chiron in the HD chart activations.
  - `include_lilith` boolean: Include Black Moon Lilith in the HD chart activations.
  - `include_visual` boolean: If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.
  - `latitude` number: Birth latitude in decimal degrees. With `longitude` it selects the IANA zone used to resolve `birth_datetime_local`, letting the historical-correction overlay apply. Not read when `birth_datetime_utc` is used.
  - `longitude` number: Birth longitude in decimal degrees. With `latitude` it selects the IANA zone used to resolve `birth_datetime_local`, letting the historical-correction overlay apply. Not read when `birth_datetime_utc` is used.
  - `planet` 'uranus' | 'saturn' | 'jupiter', required: Planet to calculate the opposition for.
  - `target_year` integer, required: Year to search for the opposition near.
  - `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
  - `visual_config` VisualRenderConfig: Optional rendering preferences for inline chart visuals.
    - `format` 'svg' | 'png': Output encoding: "svg" (default) or "png". PNG requires resvg on the server.
    - `layout` 'graph' | 'mandala': Bodygraph composition: "graph" (default) is the classic layout; "mandala" nests the same diagram inside concentric rings. Ignored for wheel renders. Honored on natal and overlay (transit, connection) bodygraph paths.
    - `size` integer: Canvas pixel dimension. Range [200, 4000]. Default 800.
    - `theme` 'light' | 'dark': Colour palette: "light" (default) or "dark".

## Response `200`

Successful Response

- HumanDesignResponse: Standardized API Response.
  - `chart` HumanDesignChartData, required: The core chart data.
    - `activations` HDActivation[], required
      - `base` integer, required: Base, the third PHS deep variable: the fifth of the tone (about 0.0052 degrees). 1-5. Always present.
      - `color` integer, required: Color, the first PHS deep variable: the sixth of the line this activation falls in (0.15625 degrees). 1-6. Always present.
      - `color_label` string: Doctrinal name of this activation's Color, present only at the four Variable positions of the PHS model — the Sun and North Node in each register (and their Earth / South Node opposites, which share the identical line/color/tone/base because 180 degrees is exactly 32 gates). Personality Sun: Motivation. Design Sun: Determination, with its fixed family name ('Consecutive - Appetite'). Personality Node: Perspective. Design Node: the Environment place-type ('Markets'). Absent on every other body, and on transit activations, because Color carries no named meaning off those positions — a real coordinate with no label, not a missing value.
      - `context` string, required
      - `gate` integer, required
      - `line` integer, required
      - `planet` string, required
      - `tone` integer, required: Tone, the second PHS deep variable: the sixth of the color (about 0.026 degrees). 1-6. Always present.
      - `tone_label` string: Doctrinal name of this activation's Tone, present only at the Variable positions where Tone names something. Personality Sun: Sense. Design Sun: Cognition. Design Node: the Environment variant that qualifies color_label's place-type ('Internal', which joins it as 'Internal - Markets'). Absent on the Personality Node, whose Tone only sets arrow direction, and on every non-Variable body and transit activation.
    - `authority` string: Inner Authority, e.g. 'Emotional', 'Sacral', 'Splenic'.
    - `centers` object, required
    - `channels` HDChannel[], required
      - `centers` string[], required
      - `gates` integer[], required
      - `id` string, required
      - `name` string, required
    - `definition` string: Definition type: 'Single', 'Split', 'Triple Split', 'Quadruple Split', or 'No Definition'.
    - `design` object, required
    - `incarnation_cross` string: Named Incarnation Cross, e.g. 'Right Angle Cross of the Sphinx'.
    - `personality` object, required
    - `profile` string: Profile, e.g. '1/3', '4/6'.
    - `strategy` string: Strategy, e.g. 'To Respond', 'To Inform'.
    - `type` string: HD Type, e.g. 'Generator', 'Manifestor', 'Projector', 'Reflector', 'Manifesting Generator'.
    - `variables` HDVariables: The 4 Transformations (Color/Tone Summary).
      - `arrows` HDVariableArrows: Derived Left/Right arrow direction for each HDVariables field, computed engine-side from the same Tone values used to build HDVariables.string — avoids re-deriving direction by parsing the string's character parity.
        - `awareness` string, required: 'L' or 'R', from the Personality Sun activation — the top-right arrow, the same body and direction the bodygraph SVG draws as g.variable--awareness (data-source=personality). Before this fix it wrongly mirrored digestion (the Design Sun).
        - `digestion` string, required: 'L' or 'R', from the Design Sun activation (top-left arrow).
        - `environment` string, required: 'L' or 'R', from the Design Node activation.
        - `perspective` string, required: 'L' or 'R', from the Personality Node activation.
      - `awareness` string, required: DEPRECATED — read 'cognition' instead. Despite the name this is the Design Sun Tone label (Cognition), not the Personality Sun the SVG's awareness arrow is drawn on. Kept with its original value so existing readers do not silently change meaning.
      - `cognition` string: Design Sun Tone label (1–6): 'Smell', 'Taste', 'Outer Vision', 'Inner Vision', 'Feeling', 'Touch'. Same value as the deprecated 'awareness' field.
      - `digestion` string, required
      - `environment` string, required
      - `motivation` string: Personality Sun Color motivation, e.g. 'Fear', 'Hope', 'Desire', 'Need', 'Guilt', 'Innocence'.
      - `perspective` string, required
      - `sense` string: Personality Sun Tone label (1–6): 'Security', 'Uncertainty', 'Action', 'Meditation', 'Judgement', 'Acceptance'. Pairs with 'motivation' (the Personality Sun Colour) on the top-right arrow.
      - `string` string, required: The code, e.g. 'PLL DLL'
  - `llm_context` HumanDesignLLMOutput: AI-friendly summary context.
    - `key_themes` string[], required
    - `summary` string, required
  - `metadata` object, required
  - `visual` VisualResult: Embedded diagram payload returned alongside chart data when include_visual=true.
    - `content_type` string, required: MIME type of the data payload.
    - `credits_charged` integer, required: Additional credits consumed to render the visual: 2, or 0 on a re-render that presented a valid render_token.
    - `data` string, required: Raw SVG string (format=svg) or standard base64-encoded PNG bytes (format=png, no data: URI prefix).
    - `format` string, required: Output format: "svg" or "png".
    - `render_token` string: Short-lived (15 min) token for re-rendering this same chart. Send it back in the X-OE-Render-Token header (or a top-level render_token body field) with a request for the same chart inputs — e.g. the same birth data in a different theme or layout — and that request is not charged again. Bound to your account and to the chart-defining inputs; any other request is charged normally.
    - `type` string, required: Diagram kind: "wheel" or "bodygraph".

## 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)