---
title: "BaZi Compatibility (八字合婚)"
method: POST
path: "/chinese/bazi/compatibility"
tags: ["chinese"]
---

# BaZi Compatibility (八字合婚)

`POST /chinese/bazi/compatibility`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/chinese/bazi/compatibility`
- 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`

Assess the compatibility between two BaZi charts using Six Harmonies (六合), Three Harmonies (三合), Six Clashes (六冲), Six Harms (六害), and Day Master element interactions.

Returns a 0–100 composite score, an assessment label (excellent / good / moderate / challenging), and a list of specific factors found.

**Note**: The 0–100 scoring is an Open Ephemeris algorithmic interpretation. BaZi compatibility analysis is nuanced and multi-layered; this endpoint provides a structured starting point.

**Metering**: 3 units per call.

## Request body

- BaZiCompatibilityRequest: Request for a BaZi compatibility comparison. chart_a and chart_b are independent BaZi requests, so each partner carries their own convention settings (year_boundary, day_boundary, true_solar_time) and their own coordinates — partners are often born in different timezones.
  - `chart_a` BaZiRequest, required: Request body for a BaZi (Four Pillars) calculation.
    - `day` integer, required: Birth day of month (1–31).
    - `day_boundary` 'zi_hour' | 'midnight': Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.
    - `format` 'json' | 'llm': Response format: json | llm.
    - `hour` integer: Birth hour (0–23). Defaults to 12 (noon). Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.
    - `latitude` number, double: Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
    - `longitude` number, double: Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
    - `minute` integer: Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it becomes load-bearing under true_solar_time, where the correction of up to ~±45 minutes is added to hour+minute/60 before the block and the 23:00 zi-hour tests are applied, and in the solar-term frame, where it shifts the birth instant by up to 59 minutes and can flip a Li Chun or Jié comparison for a birth within an hour of one.
    - `month` integer, required: Birth month (1–12).
    - `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
    - `true_solar_time` boolean: When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation of time. The correction can move the day - and therefore the day pillar and, through it, the hour stem - as well as the hour branch. The year and month pillars are compared at the true birth INSTANT and are unaffected by the correction, which transforms a clock reading rather than moving the birth. Requires latitude and longitude.
    - `year` integer, required: Gregorian birth year.
    - `year_boundary` 'lichun' | 'cny': Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.
  - `chart_b` BaZiRequest, required: Request body for a BaZi (Four Pillars) calculation.
    - `day` integer, required: Birth day of month (1–31).
    - `day_boundary` 'zi_hour' | 'midnight': Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.
    - `format` 'json' | 'llm': Response format: json | llm.
    - `hour` integer: Birth hour (0–23). Defaults to 12 (noon). Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.
    - `latitude` number, double: Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
    - `longitude` number, double: Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
    - `minute` integer: Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it becomes load-bearing under true_solar_time, where the correction of up to ~±45 minutes is added to hour+minute/60 before the block and the 23:00 zi-hour tests are applied, and in the solar-term frame, where it shifts the birth instant by up to 59 minutes and can flip a Li Chun or Jié comparison for a birth within an hour of one.
    - `month` integer, required: Birth month (1–12).
    - `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
    - `true_solar_time` boolean: When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation of time. The correction can move the day - and therefore the day pillar and, through it, the hour stem - as well as the hour branch. The year and month pillars are compared at the true birth INSTANT and are unaffected by the correction, which transforms a clock reading rather than moving the birth. Requires latitude and longitude.
    - `year` integer, required: Gregorian birth year.
    - `year_boundary` 'lichun' | 'cny': Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.

## Response `200`

Compatibility score, assessment, and contributing factors.

- BaZiCompatibilityResponse
  - `assessment` 'excellent' | 'good' | 'moderate' | 'challenging', required
  - `calculation_metadata` BaZiPairCalculationMetadata: Per-chart calculation provenance. chart_a and chart_b are independent BaZiRequests and may carry different timezones, coordinates and conventions, so one flat object would describe neither chart. Each key holds the same convention echo the single-chart BaZi endpoints return.
    - `chart_a` object
    - `chart_b` object
  - `factors` BaZiCompatibilityFactor[], required
    - `description` string, required
    - `pillar_a` string, required
    - `pillar_b` string, required
    - `score_delta` integer, required
    - `type` 'six_harmony' | 'three_harmony' | 'six_clash' | 'six_harm' | 'element_clash' | 'element_harmony', required
  - `score` integer, required
  - `success` boolean
  - `summary_note` string, required

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