# Μορφές πεδίων

Το μοντέλο που μαντεύει το όνομα του πεδίου παίρνει είτε `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` | ένα γράμμα, προεπιλογή `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` απορρίπτονται επίσης. Αναφέρονται **όλα** τα βρεθέντα πεδία μαζί, όχι μόνο το πρώτο, ώστε να μπορείς να τα διορθώσεις όλα με τη μία.

Ο λόγος είναι αυστηρός: πριν από αυτόν τον έλεγχο, ένα πεδίο που το API δεν διάβαζε έδινε σιωπηρά μετατόπιση `0`, και η απάντηση ήταν ένας σίγουρος χάρτης για UTC. Τρεις ώρες μετατόπιση ισοδυναμούν περίπου με 45° αστερισμό, δηλαδή άλλο ζώδιο που ανεβαίνει, χωρίς καμία προειδοποίηση.

## `timezone`: όνομα ζώνης αντί για μετατόπιση

Η μετατόπιση πρέπει να είναι αυτή που έδειξαν τα ρολόγια **ακριβώς εκείνης της ημερομηνίας**, και μπορεί εύκολα να δοθεί λανθασμένα χειροκίνητα: το Κίεβο τον Μάιο του 1990 ζούσε με το μοσχοβιωματικό θερινό χρόνο, 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` στην απάντηση δείχνει τη μετατόπιση που χρησιμοποιήθηκε.
- Ο χρόνος που εμφανίστηκε δύο φορές (όταν τα ρολόγια γυρίσανε πίσω) λαμβάνεται την πρώτη φορά. Ο χρόνος που δεν υπήρχε (όταν προχωρήθηκε μπροστά) παίρνει τη μετατόπιση που ίσχυε πριν τη μετάβαση.
- Χωρίς `time` (μόνο ημερομηνία ή `timeUnknown: true`) η ζώνη διαβάζεται στο τοπικό μεσημέρι.
- Απορρίπτονται με `400 INVALID_FIELD`: κενή τιμή, συντομογραφίες όπως `EST` ή `PST`, μετατόπιση γραμμένη ως κείμενο, π.χ. `+03:00`, ονόματα που δεν υπάρχουν στη βάση, και `auto` χωρίς συντεταγμένες. Τα `UTC` και `GMT` γίνονται αποδεκτά.
- Κάθε αντικείμενο επεξεργάζεται ξεχωριστά, έτσι τα `chart1` και `chart2` μπορούν να είναι σε διαφορετικές ζώνες.

<Aside type="note">
Μέχρι το 1970 η βάση ζωνών ώρας δεν είναι αξιόπιστη για κάθε τοποθεσία: το Άμστερνταμ τον Ιούνιο του 1930 επιστρέφεται ως +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` είναι το Sunshine του McRansky, `i` του Trindlem. Το όνομα του συστήματος (`"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/)