House ingresses

Beta transit searches across fixed Equal or Whole Sign cusps from a known reference chart.

POST /api/astro/house-ingresses requires a server-side API key. All plans use one standard quota unit per admitted attempt, including invalid input, calculation failure, and timeout. Do not automatically retry.

Public endpoint: https://api.astroapi.io/api/astro/house-ingresses. Send Authorization: Bearer YOUR_API_KEY and Content-Type: application/json; load the real key from your server environment.

What the calculation means

The service calculates all twelve cusps once from reference_birth. It then searches selected apparent-geocentric transit longitudes for crossings of those fixed boundaries. This is the common “transit planet enters a natal house” model. It is not a continuously moving mundane-house search.

Each event identifies the departing and entered house, the crossed cusp, and direct or retrograde motion. Houses are half-open from cusp N through, but not including, cusp N+1. A direct crossing enters the cusp's numbered house; a retrograde crossing leaves that house in the reverse direction.

Inputs and limits

• reference_birth: known date, time, latitude and longitude; optional IANA timezone defaults to UTC.
• start_utc and end_utc: whole-second UTC timestamps ending in Z, within 1900-01-01 through 2050-12-31. The start-inclusive/end-exclusive interval is greater than zero and at most 31 elapsed days.
• bodies: one or more unique lowercase values from Sun through Pluto.
• house_system: optional equal default or whole_sign.
• zodiac: optional tropical default or sidereal, with Lahiri, Raman, or Krishnamurti ayanamsa.

Placidus and Porphyry are intentionally excluded pending specialist acceptance. The route accepts no moving-house mode, uploaded kernels, arbitrary bodies, interpretations, caller search steps, URLs, or fallback house system.

Model, precision, and accuracy

Reference cusps use the existing AstroAPI house engine in the same zodiac as the transit longitudes. Transit positions use bundled JPL DE421 apparent geocentric ecliptic-of-date longitude. Fixed six-hour samples bracket crossings and bisection refines them to a 0.05-second numerical tolerance before timestamps are rounded to one second. Those settings describe model resolution, not sub-second physical accuracy.

Request

{
  "reference_birth": {
    "date": "1990-01-01",
    "time": "12:00:00",
    "timezone": "UTC",
    "lat": 40.7128,
    "lon": -74.006
  },
  "start_utc": "2026-01-01T00:00:00Z",
  "end_utc": "2026-01-08T00:00:00Z",
  "bodies": ["moon", "mercury"]
}

Response shape

{
  "type": "house_ingresses",
  "status": "beta",
  "result": {
    "house_system": "equal",
    "cusps": {
      "1": 274.639826,
      "2": 304.639826,
      "3": 334.639826,
      "4": 4.639826
    },
    "events": [
      {
        "type": "house_ingress",
        "utc": "2026-01-02T20:34:02Z",
        "body": "moon",
        "direction": "direct",
        "from_house": 6,
        "to_house": 7,
        "cusp_house": 7,
        "cusp_longitude_degrees": 94.639826,
        "longitude_degrees": 94.639868
      }
    ],
    "event_count": 4,
    "model": "de421-fixed-reference-house-ingresses-v1",
    "interval": "start_inclusive_end_exclusive",
    "timestamp_resolution_seconds": 1
  },
  "metadata": {
    "house_policy": "fixed_reference_chart_cusps_half_open",
    "moving_house_search": false,
    "search_step_hours": 6,
    "root_tolerance_seconds": 0.05,
    "interpretations": false
  }
}

The shortened response shows four of twelve cusps and one of four events. Parse the complete result.cusps and result.events values. Malformed inputs return 400. Authentication, quota, concurrency, dependency, and timeout errors retain the standard API behavior.

Node.js 22+ — server only

import { AstroAPI } from "@astroapi/node";
const api = new AstroAPI(); // Reads ASTROAPI_KEY.
const result = await api.houseIngresses({
  reference_birth: { date: "1990-01-01", time: "12:00:00", timezone: "UTC", lat: 40.7128, lon: -74.006 },
  start_utc: "2026-01-01T00:00:00Z",
  end_utc: "2026-01-08T00:00:00Z",
  bodies: ["moon", "mercury"]
});
console.log(result.result.events);

Python — server only

from astroapi_client import AstroAPIClient
api = AstroAPIClient()  # Reads ASTROAPI_KEY.
result = api.house_ingresses({
    "reference_birth": {"date": "1990-01-01", "time": "12:00:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006},
    "start_utc": "2026-01-01T00:00:00Z",
    "end_utc": "2026-01-08T00:00:00Z",
    "bodies": ["moon", "mercury"],
})
print(result["result"]["events"])

The SDK source packages use a 35-second default deadline for this bounded route. Each example makes one billable call. Keep credentials out of browser bundles and shared collections.

See the complete OpenAPI contract, Postman collection, calculation methodology, planetary events, and API overview.