CHINESE ASTROLOGY · JSON REST API

Chinese Lunar Calendar API

Add Chinese lunisolar calendar data without requiring a personal interpretation. The response exposes lunar date fields and solar-term timestamps under the documented calendar convention.

AvailablePOST /v1/chinese/calendar

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Convert Gregorian dates to Chinese lunar dates and leap-month data, with UTC and local solar-term timestamps. Explore real lunisolar JSON output.

01

Gregorian-to-Chinese lunar date conversion

02

Lunar year, month, day and leap-month flag

03

Solar terms with UTC and requested-local timestamps

04

Explicit calendar metadata from lunar-python

Send

  • birth.date and IANA timezone for the requested civil date
  • Optional local time
  • A supported locale for separate descriptive text

Receive

  • Lunar date fields and leap-month information
  • Solar-term table with instant_utc and local_datetime
  • Calendar-method metadata and localized lunar-date explanation
INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/chinese/calendar
{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  }
}
Response JSON · selected fields
{
  "request_id": "d9a353907b86a9217ab0fb58c8ae22f5",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "solar_date": "1990-05-21",
    "timezone": "Europe/Madrid",
    "lunar_date": {
      "year": 1990,
      "month": 4,
      "day": 27,
      "leap_month": false
    },
    "solar_terms": [
      {
        "name": "小寒",
        "id": "minor_cold",
        "instant_utc": "1990-01-05T14:33:14+00:00",
        "local_datetime": "1990-01-05T15:33:14+01:00"
      },
      {
        "name": "大寒",
        "id": "major_cold",
        "instant_utc": "1990-01-20T08:01:33+00:00",
        "local_datetime": "1990-01-20T09:01:33+01:00"
      }
    ],
    "method": {
      "library": "lunar-python",
      "library_version": "1.4.8",
      "calendar": "Chinese lunisolar, local Gregorian civil date",
      "solar_terms": "Beijing reference instants converted to requested timezone",
      "supported_years": [
        1900,
        2100
      ]
    }
  },
  "interpretation": {
    "locale": "en",
    "kind": "chinese/calendar",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 1,
      "selected_facts": 1,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "chinese.lunar_date",
        "title": "Chinese lunar date",
        "text": "Chinese lunar date: year 1990, month 4, day 27. Regular month. This is a calendar conversion, not a prediction.",
        "source": {
          "id": "chinese.lunar_date",
          "type": "chinese_lunar_date",
          "year": 1990,
          "month": 4,
          "day": 27,
          "leap_month": false
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 1
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/chinese/calendar' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: chinese-calendar-api-example-001' \
+  --data '{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  }
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • Lunisolar date labels in a calendar
  • Chinese calendar context beside moon phases
  • A calendar-data foundation for your own regional features

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • Solar-term source instants use the upstream Beijing convention and are converted to UTC and the requested local time zone.
  • This endpoint does not return animal-year pillars; use BaZi for the year-pillar animal under the declared solar-term boundary convention.
  • Regional festival observance and every traditional date-selection school are outside this endpoint.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Is a lunar month the same as a zodiac sign?

No. Lunisolar calendar dates are distinct from Western zodiac signs and a complete Four Pillars chart. Use BaZi for stems, branches and animal-year pillar data.

Are leap lunar months identified?

Yes. The calculated lunar date includes the leap-month convention so applications do not collapse a leap month into the ordinary month.

Can I use the term times as local sunrise?

No. Solar terms are calendar/solar-longitude events. Their instants are converted from the disclosed Beijing reference to UTC and your time zone. They are not sunrise times or local weather observations.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 1 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API