Birth data & time handling

astro_chart's horary method takes the identical object under the name questionData (the moment the question was asked). Some moment-shaped tools such as astro_moment take these fields FLAT at the top level rather than nested under birthData — see First calls in five minutes.

The flat input shape

birthData is a flat, plain-JSON object with exactly the fields below. There is no nesting, no IANA timezone names, and no separate local vs. UT switch — the timezone is a number on the same object.

Field	Type	Range	Required
`year`	integer	−4000..4000	yes
`month`	integer	1..12	yes
`day`	integer	1..31	yes
`hour`	integer	0..23	yes
`minute`	integer	0..59	yes
`second`	integer	0..59	optional (defaults 0)
`latitude`	number	−90..90	yes
`longitude`	number	−180..180	yes
`timezone`	number	−12..14	yes
`unknownTime`	boolean	—	optional

A minimal natal call for 1990-01-01 12:00 UT in London:

{
  "method": "natal",
  "birthData": {
    "year": 1990,
    "month": 1,
    "day": 1,
    "hour": 12,
    "minute": 0,
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": 0
  }
}

Timezone is a UTC-offset number

timezone is the UTC offset in hours — fractional allowed, e.g. 5.5 for India. "Europe/London" or "+01:00" fail validation. This is the #1 integration mistake. DST must already be folded in by the caller: 12:00 BST is hour: 12, timezone: 1. If your fields are already UT, pass timezone: 0. Do not double-shift: if you pre-convert to UT yourself AND pass the local offset, the chart is silently wrong.

Unknown birth time

With unknownTime: true everything clock-dependent is dropped — houses is null for every house system, ascendant/midheaven/vertex are null, the Part of Fortune is not computed, and no aspect involves an angle. Planet positions, signs, and planet-to-planet aspects still use the time fields you send.

A common convention is to pass hour: 12, minute: 0 with unknownTime: true — planets are computed for local noon, and only the Moon carries meaningful uncertainty (it moves ~13° per day, so up to ~6.5° either way).

Coordinate conventions

Signed decimal degrees, positive = north/east. London is -0.1278, New York is -74.006, Tokyo is 139.6917.

Year range and calendar

year accepts −4000..4000, astronomical numbering, interpreted on the proleptic Gregorian calendar for the whole range. Impossible dates (Feb 30) fail with a computation error. For Julian-calendar historical dates convert first with astro_date_convert (julian-gregorian method). The engine subtracts the offset at the calendar-field level — day/month/year roll over correctly across midnight.

Resolving a place

Use astro_geocode (basic) to turn a place name into coordinates:

{ "method": "basic", "query": "London" }

The response lists places with name, country, state, latitude, longitude, and timezone. Note: that timezone field is an IANA zone NAME (like "Europe/London") — you cannot pass it to birthData.timezone; resolve it to the numeric offset for the birth moment first (next section).

Resolving an IANA zone to the offset number

Use astro_date_convert (timezone) with the birth moment:

{
  "method": "timezone",
  "dateTime": { "year": 1990, "month": 7, "day": 1, "hour": 12, "minute": 0 },
  "fromZone": "Europe/London",
  "toZone": "UTC"
}

The response's from.offsetMinutes is the historically correct offset — DST included — for that moment (60 here, since London was on BST). Divide by 60 for birthData.timezone: 60 / 60 = 1, so the birth call is hour: 12, timezone: 1.

Derived charts

Derived charts treat either partner's unknown time the same way.