predictive

Calculate Lunar Return Timing

Calculate the nearest lunar return timing (Moon returns to its natal longitude) near a target datetime.

post/predictive/returns/lunar

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/predictive/returns/lunar
  • 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

Query parameters

output_modestring nullable

Deprecated: use preset+format. Accepts full|simple|llm.

formatstring

Response format: json | llm.

include_aspectsboolean nullable
include_hermetic_lotsboolean nullable

Request body

house_system'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W'

Supported house systems.

include_visualboolean

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.

search_window_daysinteger

Days to search symmetrically around target datetime (defaults depend on body)

Example request

{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 30,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}

Response

Successful Response

exact_datetimestring date-time required

Exact return datetime (UTC)

output_modestring

Output projection mode (full | simple | llm)

schema_versionstring

Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)

successboolean required

Request success status

Example response

{
  "calculation_metadata": {
    "technique_id": "natal",
    "technique_label": "Composite (Davison)",
    "technique_method": "davidson",
    "technique_version": "v1"
  },
  "location": {
    "elevation": 10,
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York"
  },
  "metadata": {
    "calculation_metadata": {
      "technique_id": "natal",
      "technique_label": "Composite (Davison)",
      "technique_method": "davidson",
      "technique_version": "v1"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.