# Formaty pól

Model, który zgaduje nazwę pola, otrzymuje albo `400`, albo, co gorsze, pewną odpowiedź o innej karcie. Poniżej dokładny kontrakt.

## Treść żądania karty

| Pole | Typ i format | Wymagane |
|---|---|---|
| `date` | `YYYY-MM-DD`, musi być rzeczywistym dniem kalendarza | tak |
| `time` | `HH:mm:ss` | tak, lub `timeUnknown: true` |
| `timezoneOffset` | liczba, godziny od UTC, np. `5.75` | nie, domyślnie `0` (UTC) |
| `timezone` | nazwa strefy IANA, np. `Europe/Kyiv`, lub `auto` | nie, a gdy zostanie wysłane, zastępuje `timezoneOffset` |
| `latitude` | stopnie dziesiętne, północ dodatnia | tak |
| `longitude` | stopnie dziesiętne, wschód dodatni | tak |
| `houseSystem` | jedna litera, domyślnie `P` | nie |
| `city` | łańcuch, tylko podpis | nie |
| `zodiacType` | `tropical` lub `sidereal` | nie |

<Aside type="caution">
`city` niczego nie geokoduje. To pole jest przeznaczone do podpisu w Twoim interfejsie, i **nigdy** nie zastępuje współrzędnych.
</Aside>

## Skrócone nazwy są odrzucane

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` zwracają `400 INVALID_FIELD` z nazwą prawidłowego pola:

```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)." } }
```
Wielkość liter i separatory nie mają znaczenia: `TZ_Offset` i `tzoffset` są odrzucane w ten sam sposób. Zgłaszane są **wszystkie** znalezione pola naraz, a nie pierwsze, aby można było je poprawić za jednym razem.

Przyczyna jest surowa: przed tą walidacją pole, którego API nie odczytywało, cicho dawało przesunięcie `0`, a odpowiedź była pewną kartą dla UTC. Trzy godziny przesunięcia to około 45° ascendenta, czyli inny znak wschodu, i bez ostrzeżenia.

## `timezone`: nazwa strefy zamiast przesunięcia

Przesunięcie musi być takie, jakie utrzymywały zegarki **w dokładnie tej dacie**, a ręczne podanie go łatwo jest błędne: Kijów w maju 1990 roku żył według moskiewskiego czasu letniego, UTC+4, a nie +3. Wyślij `timezone`, a serwer weźmie przesunięcie z bazy stref czasowych, wraz z czasem letnim.

```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
  "latitude": 50.45, "longitude": 30.52 }
```
- `auto` określa strefę na podstawie `latitude` i `longitude`. W pobliżu granicy nazwa jest dokładniejsza.
- Jeśli `timezone` i `timezoneOffset` przyszły razem, działa `timezone`. `input.timezoneOffset` w odpowiedzi pokazuje przesunięcie, które zostało użyte.
- Czas, który wystąpił dwa razy (gdy zegary były cofane), brany jest za pierwszym razem. Czas, którego nie było (gdy zegary były przesuwane do przodu), otrzymuje przesunięcie obowiązujące przed zmianą.
- Bez `time` (tylko data lub `timeUnknown: true`) strefa jest odczytywana w południe lokalnego czasu.
- Odrzucane są z kodem `400 INVALID_FIELD`: pusta wartość, skróty typu `EST` lub `PST`, przesunięcie zapisane jako tekst, np. `+03:00`, nazwy, których nie ma w bazie, oraz `auto` bez współrzędnych. `UTC` i `GMT` są akceptowane.
- Każdy obiekt jest analizowany osobno, więc `chart1` i `chart2` mogą znajdować się w różnych strefach.

<Aside type="note">
Przed 1970 rokiem baza stref czasowych nie jest wiarygodna dla każdego miejsca: Amsterdam w czerwcu 1930 roku zwraca +1, chociaż zegarki pokazywały +0:20. Jeśli lokalny czas urodzenia jest znany, wyślij `timezoneOffset`.
</Aside>

## `houseSystem`: litera, nie nazwa

Akceptowane są dokładnie te 25 kodów 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`

Wielkość liter ma znaczenie: `I` to Sunshine według Makransky, `i` według Traindl. Nazwa systemu (`"Placidus"`, `"Koch"`) zwraca `400`. Dawniej działało to przypadkowo, ponieważ silnik czyta z ciągu tylko pierwszą literę, i z tego samego powodu `"Zodiac"` cicho dawało Placidus.

## Nieznany czas urodzenia

Zamiast podawać wymyślony południe, przesyłaj `timeUnknown: true` i nie przesyłaj `time`. Wtedy `houses`, `houseAspects`, `chartSect` i `siderealTime` przychodzą jako `null`, a nie wymyślone. Szczegóły: [Konwencje API](/api-conventions/#nieznany-czas-urodzenia).

## Nieznane klucze nie są odrzucane

Treść akceptuje dodatkowe pola milcząco: nieznany klucz jest po prostu ignorowany. Dlatego błąd w nazwie pola, którego nie ma na liście odrzuceń powyżej, nie da o sobie znać. Sprawdź się ze specyfikacją: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Dalej

- [Typowe błędy](/agent-setup/mistakes/)
- [Podwodne kamienie](/agent-setup/gotchas/)