OppositionRequest
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.
Properties
| Name | Type | Description |
|---|---|---|
| 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 f |
| birth_datetime_utc | string | 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_d |
| format | string | Response format: json | llm. |
| include_chiron | boolean | Deprecated and ignored. Human Design activations are the 13 standard bodies, so this flag never changes the chart. For Chiron gate.line placements use POST /human-design/extended with `bodies: ["Chiro |
| include_lilith | boolean | Deprecated and ignored. Human Design activations are the 13 standard bodies, so this flag never changes the chart. Use POST /human-design/extended for placements of bodies outside the 13. |
| 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` |
| 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` |
| pass | integer | Which exact pass of the return to cast the chart for (1 = the first, which is the default). Only with `return_number`. A 422 lists how many passes the return has. |
| planet | string | Planet to calculate the opposition for. Any body the return endpoint accepts. |
| return_number | integer | The n-th opposition (return to the natal longitude plus 180 degrees) counted from birth (1 = the first). Resolves the date from the birth instant instead of guessing a year, so 'my second Saturn retur |
| target_year | integer | Legacy selector: the first opposition on or after 1 January of this year, searching up to 50 years ahead. Mutually exclusive with `return_number`; exactly one of the two is required. |
| timezone | object | Zone that governs `birth_datetime_local`. Optional — when omitted the zone is looked up from `latitude`/`longitude`. Supply it to override that lookup (a border town, a historical place name), or to f |
| visual_config | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-app-api-routes-human-design-opposition-request-schema.json",
"title": "OppositionRequest",
"description": "Request for a Human Design planetary opposition chart.\n\nExactly 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.",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/openephemeris-com-human-design-api-openapi.yml#/components/schemas/app__api__routes__human_design__OppositionRequest",
"properties": {
"birth_datetime_local": {
"description": "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.",
"title": "Birth Datetime Local",
"type": "string"
},
"birth_datetime_utc": {
"description": "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": "date-time",
"title": "Birth Datetime Utc",
"type": "string"
},
"format": {
"default": "json",
"description": "Response format: json | llm.",
"title": "Format",
"type": "string"
},
"include_chiron": {
"default": false,
"deprecated": true,
"description": "Deprecated and ignored. Human Design activations are the 13 standard bodies, so this flag never changes the chart. For Chiron gate.line placements use POST /human-design/extended with `bodies: [\"Chiron\"]`.",
"title": "Include Chiron",
"type": "boolean"
},
"include_lilith": {
"default": false,
"deprecated": true,
"description": "Deprecated and ignored. Human Design activations are the 13 standard bodies, so this flag never changes the chart. Use POST /human-design/extended for placements of bodies outside the 13.",
"title": "Include Lilith",
"type": "boolean"
},
"include_visual": {
"default": false,
"description": "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.",
"title": "Include Visual",
"type": "boolean"
},
"latitude": {
"description": "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.",
"maximum": 90,
"minimum": -90,
"title": "Latitude",
"type": "number"
},
"longitude": {
"description": "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.",
"maximum": 180,
"minimum": -180,
"title": "Longitude",
"type": "number"
},
"pass": {
"description": "Which exact pass of the return to cast the chart for (1 = the first, which is the default). Only with `return_number`. A 422 lists how many passes the return has.",
"maximum": 5,
"minimum": 1,
"title": "Pass",
"type": "integer"
},
"planet": {
"description": "Planet to calculate the opposition for. Any body the return endpoint accepts.",
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto",
"chiron",
"pholus"
],
"title": "Planet",
"type": "string"
},
"return_number": {
"description": "The n-th opposition (return to the natal longitude plus 180 degrees) counted from birth (1 = the first). Resolves the date from the birth instant instead of guessing a year, so 'my second Saturn return' is `return_number: 2`. Mutually exclusive with the year field. A return can consist of up to three (rarely five) exact passes when the planet turns retrograde across the degree; every pass is listed in `metadata.passes` and `pass` picks which one the chart is cast for. Refused with 422 when the date falls outside the supported ephemeris range (1550-2650, and 1600-2200 for Chiron and Pholus).",
"maximum": 400,
"minimum": 1,
"title": "Return Number",
"type": "integer"
},
"target_year": {
"description": "Legacy selector: the first opposition on or after 1 January of this year, searching up to 50 years ahead. Mutually exclusive with `return_number`; exactly one of the two is required.",
"title": "Target Year",
"type": "integer"
},
"timezone": {
"$ref": "#/$defs/TimezoneInput",
"description": "Zone that governs `birth_datetime_local`. Optional — when omitted the zone is looked up from `latitude`/`longitude`. Supply it to override that lookup (a border town, a historical place name), or to force `time_standard`/`fold_preference`. Ignored when `birth_datetime_utc` is used."
},
"visual_config": {
"$ref": "#/$defs/VisualRenderConfig"
}
},
"required": [
"planet"
],
"type": "object",
"$defs": {
"TimezoneInput": {
"additionalProperties": false,
"description": "Timezone input using IANA names or UTC offsets.",
"properties": {
"fold_preference": {
"description": "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.",
"enum": [
"earlier",
"later"
],
"title": "Fold Preference",
"type": "string"
},
"iana_name": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
}
],
"description": "IANA timezone name",
"title": "Iana Name"
},
"time_standard": {
"description": "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.",
"enum": [
"auto",
"standard",
"daylight"
],
"title": "Time Standard",
"type": "string"
},
"utc_offset": {
"anyOf": [
{
"type": "number"
}
],
"description": "UTC offset in hours",
"title": "Utc Offset"
}
},
"title": "TimezoneInput",
"type": "object"
},
"VisualRenderConfig": {
"additionalProperties": false,
"description": "Optional rendering preferences for inline chart visuals.",
"properties": {
"format": {
"default": "svg",
"description": "Output encoding: \"svg\" (default) or \"png\". PNG requires resvg on the server.",
"enum": [
"svg",
"png"
],
"title": "Format",
"type": "string"
},
"layout": {
"default": "graph",
"description": "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.",
"enum": [
"graph",
"mandala"
],
"title": "Layout",
"type": "string"
},
"size": {
"default": 800,
"description": "Canvas pixel dimension. Range [200, 4000]. Default 800.",
"maximum": 4000,
"minimum": 200,
"title": "Size",
"type": "integer"
},
"theme": {
"default": "light",
"description": "Colour palette: \"light\" (default) or \"dark\".",
"enum": [
"light",
"dark"
],
"title": "Theme",
"type": "string"
}
},
"title": "VisualRenderConfig",
"type": "object"
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/json-schemas/openephemeris-com-app-api-routes-human-design-opposition-request"
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.