# Format Bidang

Model yang menebak nama field akan menerima `400`, atau yang lebih buruk, respons yakin tentang chart lain. Berikut kontrak yang tepat.

## Badan permintaan chart

| Field | Tipe dan format | Wajib |
|---|---|---|
| `date` | `YYYY-MM-DD`, dan ini harus menjadi hari kalender yang nyata | ya |
| `time` | `HH:mm:ss` | ya, atau `timeUnknown: true` |
| `timezoneOffset` | angka, jam dari UTC, contoh `5.75` | tidak, default `0` (UTC) |
| `timezone` | nama zona IANA, contoh `Europe/Kyiv`, atau `auto` | tidak, dan bila dikirim, menggantikan `timezoneOffset` |
| `latitude` | derajat desimal, utara positif | ya |
| `longitude` | derajat desimal, timur positif | ya |
| `houseSystem` | satu huruf, default `P` | tidak |
| `city` | string, hanya label | tidak |
| `zodiacType` | `tropical` atau `sidereal` | tidak |

<Aside type="caution">
`city` tidak melakukan geocode apa pun. Ini adalah field untuk label di antarmuka kamu, dan **tidak pernah** menggantikan koordinat.
</Aside>

## Singkatan ditolak

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` mengembalikan `400 INVALID_FIELD` dengan nama field yang benar:

```json
{ "error": { "code": "INVALID_FIELD",
  "message": "Unsupported field \"tz\". Rename it to \"timezoneOffset\" (numeric hours from UTC, e.g. 5.75; a zone name goes in timezone)." } }
```

Huruf besar/kecil dan pemisah nilai tidak diizinkan: `TZ_Offset` dan `tzoffset` ditolak juga. **Semua** field yang ditemukan dilaporkan sekaligus, bukan yang pertama, sehingga dapat diperbaiki sekaligus.

Alasannya keras: sebelum pemeriksaan ini, field yang tidak dibaca API secara diam-diam memberikan offset `0`, dan respons menjadi chart yakin untuk UTC. Offset tiga jam kira-kira 45° ascendant, artinya tanda lain yang naik, tanpa peringatan apapun.

## `timezone`: nama zona alih-alih offset

Offset harus menjadi yang dipakai jam pada **tanggal itu**, dan mudah salah menentukannya secara manual: Kyiv pada Mei 1990 menggunakan waktu musim panas Moskow, UTC+4, bukan +3. Kirim `timezone`, dan server akan mengambil offset dari basis zona waktu, termasuk daylight saving.

```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
  "latitude": 50.45, "longitude": 30.52 }
```

- `auto` menentukan zona berdasarkan `latitude` dan `longitude`. Di dekat perbatasan nama lebih akurat.
- Jika `timezone` dan `timezoneOffset` dikirim bersamaan, yang berlaku adalah `timezone`. `input.timezoneOffset` dalam respons menunjukkan offset yang digunakan.
- Waktu yang berulang (ketika jam digulung mundur) diambil dari pertama kali. Waktu yang tidak ada (ketika jam digulung maju) mendapatkan offset yang berlaku sebelum perubahan.
- Tanpa `time` (hanya tanggal atau `timeUnknown: true`) zona dibaca pada tengah hari setempat.
- Ditolak dengan `400 INVALID_FIELD`: nilai kosong, singkatan seperti `EST` atau `PST`, offset yang ditulis sebagai teks seperti `+03:00`, nama yang tidak ada di basis, dan `auto` tanpa koordinat. `UTC` dan `GMT` diterima.
- Setiap objek diproses terpisah, sehingga `chart1` dan `chart2` dapat berada di zona yang berbeda.

<Aside type="note">
Sebelum tahun 1970 basis zona waktu tidak andal untuk setiap lokasi: Amsterdam pada Juni 1930 kembali sebagai +1, meskipun jam menunjukkan +0:20. Jika waktu setempat kelahiran diketahui, kirim `timezoneOffset`.
</Aside>

## `houseSystem`: huruf, bukan nama

Diterima tepat 25 kode Swiss Ephemeris berikut:

`P` `K` `R` `C` `E` `W` `B` `M` `O` `A` `T` `V` `D` `F` `G` `H` `I` `i` `L` `N` `Q` `S` `U` `X` `Y`

Huruf besar penting: `I` adalah Sunshine menurut McRansky, `i` menurut Trundle. Nama sistem (`"Placidus"`, `"Koch"`) mengembalikan `400`. Sebelumnya berfungsi secara acak karena engine hanya membaca huruf pertama dari string, dan karena alasan yang sama `"Zodiac"` secara diam-diam memberikan Placidus.

## Waktu kelahiran tidak diketahui

Alih-alih menggunakan tengah hari fiktif, kirim `timeUnknown: true` dan jangan kirim `time`. Maka `houses`, `houseAspects`, `chartSect`, dan `siderealTime` akan menjadi `null`, bukan nilai fiktif. Detail: [Konvensi API](/api-conventions/#невідомий-час-народження).

## Kunci tidak dikenal tidak ditolak

Badan menerima field tambahan secara diam-diam: kunci yang tidak dikenal hanya diabaikan. Jadi kesalahan pada nama field yang tidak ada dalam daftar penolakan di atas tidak akan terdeteksi. Lihat spesifikasi: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Selanjutnya

- [Kesalahan umum](/agent-setup/mistakes/)
- [Hal-hal yang perlu diwaspadai](/agent-setup/gotchas/)