# Định dạng trường
Mô hình đoán tên trường sẽ nhận được hoặc `400`, hoặc, hơn thế nữa, một phản hồi chắc chắn về một bản đồ khác. Dưới đây là hợp đồng chính xác.
## Thân của yêu cầu bản đồ
| Trường | Kiểu và định dạng | Bắt buộc |
|---|---|---|
| `date` | `YYYY-MM-DD`, và phải là ngày thực tế trong lịch | Có |
| `time` | `HH:mm:ss` | Có, hoặc `timeUnknown: true` |
| `timezoneOffset` | số, giờ lệch UTC, ví dụ `5.75` | Không, mặc định là `0` (UTC) |
| `timezone` | tên múi giờ IANA, ví dụ `Europe/Kyiv`, hoặc `auto` | Không, và khi được gửi, nó sẽ thay thế `timezoneOffset` |
| `latitude` | độ thập phân, phía Bắc dương | Có |
| `longitude` | độ thập phân, phía Đông dương | Có |
| `houseSystem` | một chữ cái, mặc định là `P` | Không |
| `city` | chuỗi, chỉ dùng để ký hiệu | Không |
| `zodiacType` | `tropical` hoặc `sidereal` | Không |
## Các viết tắt bị từ chối
`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` trả về `400 INVALID_FIELD` với tên trường đúng:
```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)." } }
```
Chữ hoa/thường và dấu phân cách không có ý nghĩa: `TZ_Offset` và `tzoffset` bị từ chối theo cùng cách. **Tất cả** các trường được tìm thấy sẽ được báo cáo cùng lúc, không phải chỉ trường đầu tiên, để bạn có thể sửa chúng tất cả trong một lần.
Lý do vì sự khắt khe: trước khi thực hiện kiểm tra này, trường mà API không đọc sẽ im lặng cung cấp độ lệch `0`, và phản hồi sẽ là một bản đồ chắc chắn cho UTC. Ba giờ lệch tương đương khoảng 45° ascendant, tức là một dấu mọc khác, và không có bất kỳ cảnh báo nào.
## `timezone`: tên múi giờ thay vì độ lệch
Độ lệch phải là quello mà đồng hồ đang giữ **trong ngày đó**, và việc chỉ định thủ công dễ dẫn đến lỗi: Kyiv vào tháng 5 năm 1990 đang sử dụng giờ mùa đông của Moscow, UTC+4, thay vì +3. Gửi `timezone`, và máy chủ sẽ lấy độ lệch từ cơ sở dữ liệu múi giờ, kèm theo giờ mùa đông.
```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
"latitude": 50.45, "longitude": 30.52 }
```
- `auto` xác định múi giờ dựa trên `latitude` và `longitude`. Gần ranh giới, tên sẽ chính xác hơn.
- Nếu cả `timezone` và `timezoneOffset` được gửi cùng lúc, thì `timezone` sẽ có hiệu lực. `input.timezoneOffset` trong phản hồi sẽ hiển thị độ lệch đã được sử dụng.
- Thời gian xuất hiện hai lần (khi đồng hồ được lùi lại) sẽ được lấy lần đầu tiên. Thời gian không tồn tại (khi đồng hồ được tiến lên) sẽ nhận được độ lệch áp dụng trước khi thay đổi.
- Không có `time` (chỉ có ngày hoặc `timeUnknown: true`), múi giờ được đọc vào giờ trưa địa phương.
- Bị từ chối với mã `400 INVALID_FIELD`: giá trị trống, các viết tắt như `EST` hoặc `PST`, độ lệch được viết dưới dạng văn bản như `+03:00`, tên không có trong cơ sở dữ liệu, và `auto` mà không có tọa độ. `UTC` và `GMT` được chấp nhận.
- Mỗi đối tượng được phân tích riêng, vì vậy `chart1` và `chart2` có thể thuộc các múi giờ khác nhau.
## `houseSystem`: chữ cái, không phải tên
Chấp nhận chính xác 25 mã sau của Swiss Ephemeris:
`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`
Chữ hoa/thường có ý nghĩa: `I` là hệ Sunshine của McCranie, `i` là hệ của TraiNDL. Tên hệ thống (`"Placidus"`, `"Koch"`) sẽ trả về `400`. Trước đây nó hoạt động ngẫu nhiên vì 엔진 chỉ đọc chữ cái đầu tiên của chuỗi, và vì lý do đó `"Zodiac"` im lặng đưa ra Placidus.
## Thời gian sinh không biết
Thay vì gửi một giờ trưa giả định, hãy gửi `timeUnknown: true` và không gửi `time`. Khi đó, `houses`, `houseAspects`, `chartSect` và `siderealTime` sẽ có giá trị `null` thay vì được giả định. Chi tiết: [Các quy ước API](/api-conventions/#невідомий-час-народження).
## Các khóa không được biết không bị từ chối
Thể yêu cầu chấp nhận các trường thừa một cách im lặng: khóa không được biết sẽ bị bỏ qua. Do đó, lỗi trong tên trường không có trong danh sách từ chối ở trên sẽ không được thể hiện. Kiểm tra với thông số kỹ thuật: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).
## Tiếp theo
- [Các lỗi thường gặp](/agent-setup/mistakes/)
- [Các rủi ro ẩn](/agent-setup/gotchas/)