# 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](../reference/tools/astro_moment.md) take these fields
FLAT at the top level rather than nested under `birthData` — see
[First calls in five minutes](./public-quickstart.md).

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

```json
{
  "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](../reference/tools/astro_date_convert.md)
(`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](../reference/tools/astro_geocode.md) (`basic`) to turn a
place name into coordinates:

```json
{ "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](../reference/tools/astro_date_convert.md)
(`timezone`) with the birth moment:

```json
{
  "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.

## Related

- [House systems](./house-systems.md)
- [Aspects & orbs](./aspects-and-orbs.md)
- [Zodiacs & ayanamsas](./zodiacs-and-ayanamsas.md)
- [Choosing a tool](./choosing-a-tool.md)
- [Reference](/reference.md)