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

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:

{ "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.

{ "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.

`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.

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.

Dalej

Przydatne?

Запропонувати правку

Ostatnia aktualizacja: 18 wrz 2026