# フィールド形式

フィールド名を推測するモデルは、`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` | 1文字、デフォルトは `P` | いいえ |
| `city` | 文字列、ラベルのみ | いいえ |
| `zodiacType` | `tropical` または `sidereal` | いいえ |

<Aside type="caution">
`city` はジオコーディングしません。このフィールドはインターフェース上のラベル用で、座標の代わりになることは **決して** ありません。
</Aside>

## 短縮形は受け付けません

`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` も同様に拒否されます。**すべて** の検出されたフィールドが一度に報告され、最初の1つだけでなく、一度に修正できるようになっています。

厳格な理由: このチェック以前に 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` は使用されたオフセットを示します。
- 時計が2回戻された（夏時間終了）場合、最初の時刻が使用されます。時計が進められた（夏時間開始）場合、その時刻は変更前のオフセットが適用されます。
- `time` がない場合（日付のみまたは `timeUnknown: true`）、タイムゾーンは現地正午で読み取られます。
- `400 INVALID_FIELD` が返されます：空の値、`EST` や `PST` のような略称、テキストで記述されたオフセット（例: `+03:00`）、データベースに存在しない名前、座標なしの `auto`。`UTC` と `GMT` は受け入れられます。
- 各オブジェクトは個別に処理されるため、`chart1` と `chart2` は異なるタイムゾーンに設定できます。

<Aside type="note">
1970年以前はタイムゾーンデータベースがすべての場所に対して信頼できるわけではありません。例として、1930年6月のアムステルダムは +1 と返されますが、時計は +0:20 を示していました。出生時のローカル時刻が分かる場合は `timezoneOffset` を送信してください。
</Aside>

## `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/)