---
title: "Calculate midpoints for datetime"
method: POST
path: "/ephemeris/midpoints"
tags: ["ephemeris"]
---

# Calculate midpoints for datetime

`POST /ephemeris/midpoints`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/midpoints`
- 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 zodiacal midpoints from planetary longitudes, detecting conjunctions and oppositions to sensitive points. Supports sort-by-type, tree grouping, and dial-degree formatting. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~65%.

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

- MidpointsCalculationRequest: Request for midpoint calculations.
  - `arc_type` 'short' | 'long' | 'both': Type of midpoint arc to calculate: 'short' (direct), 'long' (opposite), or 'both'
  - `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
  - `house_system` string: Optional house system for angle calculation (e.g., 'P', 'W'). Defaults to server settings when omitted.
  - `include_angles` boolean: Whether to include chart angles (ASC, MC, etc.) in midpoint pairs
  - `include_occupied` boolean: Return only midpoints that a body occupies within `orb`. Occupancy (`occupied_by`, `occupants`) is reported either way.
  - `latitude` number: Optional latitude for computing angles when include_angles=True. If include_angles=True, latitude and longitude must be provided.
  - `longitude` number: Optional longitude for computing angles when include_angles=True. If include_angles=True, latitude and longitude must be provided.
  - `node_source` 'true_osculating' | 'mean': Add the lunar North Node to the bodies: `true_osculating` or `mean`. Omit for no Node.
  - `orb` number: Orb in degrees for occupied-midpoint detection (default 1.0°).
  - `sort_by` 'degree' | 'planet1' | 'planet2': Optional sorting: by longitude degree, first planet name, or second planet name

## Response `200`

Successful Response

- MidpointsCalculationResponse: Response from midpoints calculation endpoint.
  - `metadata` object, required: Calculation metadata and settings
  - `midpoints` MidpointResult[], required: Calculated midpoints
    - `arc_type` string, required: Arc type: 'short' or 'long'
    - `longitude` number, required: Midpoint longitude in degrees (0-360)
    - `occupants` MidpointOccupant[]: The bodies or points occupying this midpoint, each with its orb. Absent when none.
      - `aspect` 'conjunction' | 'opposition', required: conjunction: on this midpoint's longitude. opposition: on the opposite point of the same axis.
      - `body` string, required: Occupying body or point.
      - `orb` number, double, required: Distance from exact, in degrees.
    - `occupied_by` string[]: Names of the bodies or points occupying this midpoint within orb. Absent when none.
    - `planet1` string, required: First planet/point name
    - `planet2` string, required: Second planet/point name
    - `sign` string, required: Zodiac sign of midpoint
    - `sign_degrees` number, required: Degrees within sign (0-30)
  - `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)