# 필드 형식
필드 이름을 추측하는 모델은 `400`을 받거나, 더 나쁘게는 다른 차트에 대한 확신 있는 응답을 받게 돼. 아래는 정확한 계약이야.
## 차트 요청 본문
| 필드 | 유형 및 형식 | 필수 |
|---|---|---|
| `date` | `YYYY-MM-DD`, 그리고 실제 달력 날짜여야 해 | 예 |
| `time` | `HH:mm:ss` | 예, 또는 `timeUnknown: true` |
| `timezoneOffset` | 숫자, UTC 기준 시간 차이, 예: `5.75` | 아니오, 기본값 `0` (UTC) |
| `timezone` | IANA 시간대 이름, 예: `Europe/Kyiv`, 또는 `auto` | 아니오, 보내면 `timezoneOffset`을 대체해 |
| `latitude` | 소수점 위도, 북쪽은 양수 | 예 |
| `longitude` | 소수점 경도, 동쪽은 양수 | 예 |
| `houseSystem` | 한 글자, 기본값 `P` | 아니오 |
| `city` | 문자열, 서명만 | 아니오 |
| `zodiacType` | `tropical` 또는 `sidereal` | 아니오 |
## 짧은 표기는 허용되지 않아
`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone`는 올바른 필드 이름과 함께 `400 INVALID_FIELD`를 반환해:
```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)." } }
```
대소문자와 구분자는 허용되지 않아: `TZ_Offset`와 `tzoffset`도 동일하게 거부돼. **모든** 발견된 필드가 한 번에 보고돼, 첫 번째만이 아니라 한 번에 수정할 수 있게.
엄격한 이유: 이 검증 전에 API가 읽지 않은 필드는 조용히 오프셋 `0`을 주었고, 응답은 UTC에 대한 확신 있는 차트가 되었어. 3시간 오프셋은 대략 45° 상승점이라, 다른 상승 사인이 되고 경고도 없었지.
## `timezone`: 오프셋 대신 시간대 이름
오프셋은 **그 날짜의** 시계가 가리키던 값이어야 하고, 수동으로 잘못 지정하기 쉬워: 1990년 5월의 키예프는 모스크바 여름시간인 UTC+4를 사용했지, +3이 아니라. `timezone`을 보내면 서버가 시간대 데이터베이스에서 오프셋과 여름시간을 가져와.
```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
"latitude": 50.45, "longitude": 30.52 }
```
- `auto`는 `latitude`와 `longitude`를 기준으로 시간대를 결정해. 경계 근처에서는 이름이 더 정확해.
- `timezone`과 `timezoneOffset`이 함께 오면, `timezone`이 우선해. 응답의 `input.timezoneOffset`은 사용된 오프셋을 보여줘.
- 두 번 반복된 시간(시계가 뒤로 돌렸을 때)은 첫 번째 값을 사용해. 존재하지 않았던 시간(앞으로 돌렸을 때)은 전환 전 적용된 오프셋을 받아.
- `time` 없이(날짜만 있거나 `timeUnknown: true`인 경우) 시간대는 현지 정오를 기준으로 읽혀.
- `400 INVALID_FIELD`로 거부되는 경우: 빈 값, `EST`나 `PST` 같은 약어, 텍스트로 기록된 오프셋(`+03:00`), 데이터베이스에 없는 이름, 좌표 없이 `auto`. `UTC`와 `GMT`는 허용돼.
- 각 객체는 별도로 처리되니, `chart1`과 `chart2`가 서로 다른 시간대에 있을 수 있어.
## `houseSystem`: 문자, 이름이 아니라
다음 25개의 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`
대소문자가 의미 있어: `I`는 MacRae의 Sunshine, `i`는 Trundle의. 시스템 이름(`"Placidus"`, `"Koch"`)은 `400`을 반환해. 이전엔 엔진이 문자열에서 첫 글자만 읽어서 우연히 동작했으며, 같은 이유로 `"Zodiac"`은 조용히 Placidus를 반환했어.
## 알 수 없는 출생 시간
가짜 정오 대신 `timeUnknown: true`를 보내고 `time`은 보내지 않아. 그러면 `houses`, `houseAspects`, `chartSect`, `siderealTime`이 `null`로 오고, 가짜 값이 아니야. 자세한 내용: [API 컨벤션](/api-conventions/#невідомий-час-народження).
## 알 수 없는 키는 거부되지 않아
본문은 알 수 없는 필드를 조용히 받아들여: 알 수 없는 키는 그냥 무시돼. 그래서 위의 거부 목록에 없는 필드 이름 오류는 눈에 띄지 않아. 사양을 확인해: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).
## 다음
- [일반적인 오류](/agent-setup/mistakes/)
- [주의할 점](/agent-setup/gotchas/)