# Formate de câmpuri
## Corpul cererii de hartă
| Câmp | Tip și format | Obligatoriu |
|---|---|---|
| `date` | `YYYY-MM-DD`, și trebuie să fie o zi calendaristică reală | da |
| `time` | `HH:mm:ss` | da, sau `timeUnknown: true` |
| `timezoneOffset` | număr, ore față de UTC, de ex. `5.75` | nu, implicit `0` (UTC) |
| `timezone` | nume de zonă IANA, de ex. `Europe/Kyiv`, sau `auto` | nu, și când este trimis, înlocuiește `timezoneOffset` |
| `latitude` | grade zecimale, nord pozitiv | da |
| `longitude` | grade zecimale, est pozitiv | da |
| `houseSystem` | o literă, implicit `P` | nu |
| `city` | șir, doar etichetă | nu |
| `zodiacType` | `tropical` sau `sidereal` | nu |
## Abrevierile sunt respinse
`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` returnează `400 INVALID_FIELD` cu numele câmpului corect:
```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)." } }
```
Registrul și separatoarele valorii nu contează: `TZ_Offset` și `tzoffset` sunt respinse la fel. **Toate** câmpurile găsite sunt raportate simultan, nu doar primul, pentru a le poți corecta dintr-o dată.
Motivul este strict: înainte de această verificare, câmpul pe care API-ul nu îl citea dădea în tăcere un offset `0`, iar răspunsul era o hartă sigură pentru UTC. Un offset de trei ore înseamnă aproximativ 45° ascendent, adică un alt semn ascendent, fără niciun avertisment.
## `timezone`: nume de zonă în loc de offset
Offset-ul trebuie să fie cel pe care ceasurile îl aveau **exact în acea dată**, și poate fi ușor specificat greșit manual: Kiev în mai 1990 folosea ora de vară a Moscovei, UTC+4, nu +3. Trimite `timezone` și serverul va prelua offset-ul din baza de fusuri orare, inclusiv ora de vară.
```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
"latitude": 50.45, "longitude": 30.52 }
```
- `auto` determină zona pe baza `latitude` și `longitude`. Aproape de frontieră, numele este mai precis.
- Dacă `timezone` și `timezoneOffset` sunt trimise împreună, se aplică `timezone`. `input.timezoneOffset` în răspuns arată offset-ul folosit.
- Ora care a fost dublă (când ceasurile s-au dat înapoi) este luată la prima apariție. Ora care nu a existat (când s-a dat înainte) primește offset-ul care era în vigoare înainte de schimbare.
- Fără `time` (doar data sau `timeUnknown: true`) zona este citită la amiază locală.
- Sunt respinse cu `400 INVALID_FIELD`: valoare goală, abrevieri ca `EST` sau `PST`, offset scris ca text, de ex. `+03:00`, nume care nu există în baza de date și `auto` fără coordonate. `UTC` și `GMT` sunt acceptate.
- Fiecare obiect este procesat separat, așa că `chart1` și `chart2` pot fi în zone diferite.
## `houseSystem`: literă, nu nume
Sunt acceptate exact aceste 25 de coduri 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`
Registrul contează: `I` este Sunshine după McCantski, `i` după Trindlem. Numele sistemului (`"Placidus"`, `"Koch"`) returnează `400`. Anterior funcționa accidental, deoarece motorul citește din șir doar prima literă, și din același motiv `"Zodiac"` returna în tăcere Placidus.
## Timp de naștere necunoscut
În loc de un prânz inventat, transmite `timeUnknown: true` și nu transmite `time`. Astfel `houses`, `houseAspects`, `chartSect` și `siderealTime` vin `null`, nu inventate. Detalii: [Convețiile API](/api-conventions/#невідомий-час-народження).
## Cheile necunoscute nu sunt respinse
Corpul acceptă în tăcere câmpuri suplimentare: cheia necunoscută este pur și simplu ignorată. Astfel, o eroare în numele unui câmp care nu apare în lista de respingeri de mai sus nu va fi semnalată. Verifică specificația: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).
## În continuare
- [Erori tipice](/agent-setup/mistakes/)
- [Capcane](/agent-setup/gotchas/)