# Mezőformátumok

Az a modell, amely kitalálja a mező nevét, vagy `400`-at kap, vagy, ami még rosszabb, egy biztos választ egy másik térképről. Alább a pontos szerződés.

## Kártya lekérdezés teste

| Mező | Típus és formátum | Kötelező |
|---|---|---|
| `date` | `YYYY-MM-DD`, és ez egy valós naptári nap kell legyen | igen |
| `time` | `HH:mm:ss` | igen, vagy `timeUnknown: true` |
| `timezoneOffset` | szám, órák az UTC-től, pl. `5.75` | nem, alapértelmezett `0` (UTC) |
| `timezone` | IANA zóna neve, pl. `Europe/Kyiv`, vagy `auto` | nem, de ha elküldik, felülírja a `timezoneOffset`-t |
| `latitude` | decimális fok, észak pozitív | igen |
| `longitude` | decimális fok, kelet pozitív | igen |
| `houseSystem` | egy betű, alapértelmezett `P` | nem |
| `city` | karakterlánc, csak címke | nem |
| `zodiacType` | `tropical` vagy `sidereal` | nem |

<Aside type="caution">
`city` semmit sem geokódol. Ez a mező a felhasználói felületedben a címkéhez, és **soha** nem helyettesíti a koordinátákat.
</Aside>

## Rövidítések elutasítva

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` `400 INVALID_FIELD`-et ad vissza a helyes mező nevével:

```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)." } }
```

Az érték nagybetű- és elválasztó karakterei nem számítanak: `TZ_Offset` és `tzoffset` ugyanúgy elutasítva. **Minden** megtalált mező egyszerre kerül jelentésre, nem csak az első, hogy egyszerre javítható legyen.

Az ok szigorú: ezelőtt, mielőtt ez az ellenőrzés megtörtént volna, a mező, amelyet az API nem olvasott, csendben `0` eltolást adott, és a válasz egy biztos UTC térkép volt. Három óra eltolás nagyjából 45° ascendenst jelent, vagyis egy másik felkelő jegyet, figyelmeztetés nélkül.

## `timezone`: zóna neve az eltolás helyett

Az eltolásnak annak a napnak kell lennie, amelyet a órák **pontosan azon a dátumon** mutattak, és kézzel könnyen hibásan megadható: 1990 májusában Kijev moszkvai nyári idő szerint UTC+4-et használt, nem +3-at. Küldd el a `timezone`-t, és a szerver az időzóna adatbázisból veszi az eltolást, a nyári idővel együtt.

```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
  "latitude": 50.45, "longitude": 30.52 }
```

- `auto` a zónát a `latitude` és `longitude` alapján határozza meg. Határ közelében a név pontosabb.
- Ha a `timezone` és a `timezoneOffset` együtt érkeznek, a `timezone` érvényesül. A válaszban az `input.timezoneOffset` azt az eltolást mutatja, amelyet felhasználtak.
- Az az idő, amelyik kétszer is létezett (amikor az órák visszafelé álltak), az első előfordulás alapján kerül felhasználásra. Az az idő, amelyik nem létezett (amikor előre álltak), az átváltás előtti eltolást kapja.
- `time` nélkül (csak dátum vagy `timeUnknown: true`) a zóna a helyi délhez igazodik.
- `400 INVALID_FIELD`-et ad vissza: üres érték, olyan rövidítések mint `EST` vagy `PST`, szövegesen megadott eltolás, mint `+03:00`, olyan nevek, amelyek nincsenek az adatbázisban, és `auto` koordináták nélkül. `UTC` és `GMT` elfogadott.
- Minden objektum külön kerül feldolgozásra, így a `chart1` és a `chart2` különböző zónákban lehetnek.

<Aside type="note">
1970 előtt az időzóna adatbázis nem megbízható minden helyhez: 1930 júniusában Amszterdamként +1-et ad vissza, bár az órák +0:20-at mutattak. Ha a születés helyi ideje ismert, küldd el a `timezoneOffset`-t.
</Aside>

## `houseSystem`: betű, nem név

Pontosan ez a 25 Swiss Ephemeris kód elfogadott:

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

A nagybetű/kisbetű jelentős: `I` a Sunshine MacRansky szerint, `i` a Trundle szerint. A rendszer neve (`"Placidus"`, `"Koch"`) `400`-at ad vissza. Korábban véletlenszerűen működött, mert a motor csak az első betűt olvassa a karakterláncból, és ugyanebből az okból a `"Zodiac"` csendben Placidus-t adott.

## Ismeretlen születési idő

A kitalált dél helyett add meg `timeUnknown: true`-t, és ne küldd el a `time`-ot. Így a `houses`, `houseAspects`, `chartSect` és a `siderealTime` `null` értékkel érkeznek, nem kitaláltakkal. Részletek: [API konvenciók](/api-conventions/#невідомий-час-народження).

## Ismeretlen kulcsok nem kerülnek elutasításra

A test csendben elfogadja a felesleges mezőket: az ismeretlen kulcs egyszerűen figyelmen kívül marad. Így egy mezőnév hibája, amely nincs a fenti elutasítási listában, nem fog jelezni. Hivatkozz a specifikációra: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Tovább

- [Szokásos hibák](/agent-setup/mistakes/)
- [Csapdák](/agent-setup/gotchas/)