# Formati dei campi

Un modello che indovina il nome di un campo riceve un `400` o, peggio, una risposta sicura su un'altra carta. Di seguito è riportato il contratto esatto.

## Corpo della richiesta della carta

| Campo | Tipo e formato | Obbligatorio |
|---|---|---|
| `date` | `YYYY-MM-DD`, e deve essere un giorno di calendario reale | sì |
| `time` | `HH:mm:ss` | sì, o `timeUnknown: true` |
| `timezoneOffset` | numero, ore da UTC, es. `5.75` | no, predefinito `0` (UTC) |
| `timezone` | nome della zona IANA, es. `Europe/Kyiv`, o `auto` | no, e quando inviato, sostituisce `timezoneOffset` |
| `latitude` | gradi decimali, nord positivo | sì |
| `longitude` | gradi decimali, est positivo | sì |
| `houseSystem` | una singola lettera, predefinito `P` | no |
| `city` | stringa, solo per etichetta | no |
| `zodiacType` | `tropical` o `sidereal` | no |

<Aside type="caution">
`city` non geocodifica nulla. Questo campo è per un'etichetta nella tua interfaccia e **non** sostituisce mai le coordinate.
</Aside>

## Le abbreviazioni sono rifiutate

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` restituiscono `400 INVALID_FIELD` con il nome del campo corretto:

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

Maiuscole/minuscole e separatori non contano: `TZ_Offset` e `tzoffset` sono rifiutati allo stesso modo. **Tutti** i campi trovati sono segnalati immediatamente, non solo il primo, in modo da poter correggere tutto in una volta.

Il motivo è severo: prima di questa convalida, un campo che l'API non leggeva dava silenziosamente un offset di `0`, e la risposta era una carta sicura per UTC. Tre ore di offset sono circa 45° di ascendente, il che significa un segno ascendente diverso, e nessun avviso.

## `timezone`: nome della zona invece dell'offset

L'offset deve essere quello che gli orologi mantenevano **esattamente in quella data**, ed è facile specificarlo erroneamente a mano: Kiev nel maggio 1990 era in ora legale di Mosca, UTC+4, non +3. Invia `timezone`, e il server prenderà l'offset dal database dei fusi orari, inclusa l'ora legale.

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

- `auto` determina la zona in base a `latitude` e `longitude`. Vicino a un confine, il nome è più preciso.
- Se `timezone` e `timezoneOffset` sono inviati insieme, `timezone` ha la precedenza. `input.timezoneOffset` nella risposta mostra l'offset che è stato utilizzato.
- Un'ora che si è verificata due volte (quando gli orologi sono stati spostati indietro) viene presa la prima volta. Un'ora che non si è verificata (quando gli orologi sono stati spostati avanti) riceve l'offset che era in vigore prima del cambio.
- Senza `time` (solo data o `timeUnknown: true`), la zona viene letta a mezzogiorno locale.
- Sono rifiutati con `400 INVALID_FIELD`: valore vuoto, abbreviazioni come `EST` o `PST`, offset scritto come testo, come `+03:00`, nomi non presenti nel database, e `auto` senza coordinate. `UTC` e `GMT` sono accettati.
- Ogni oggetto viene analizzato separatamente, quindi `chart1` e `chart2` possono essere in zone diverse.

<Aside type="note">
Prima del 1970, il database dei fusi orari non è affidabile per ogni luogo: Amsterdam nel giugno 1930 viene restituita come +1, anche se gli orologi mostravano +0:20. Se l'ora locale di quella nascita è nota, invia `timezoneOffset`.
</Aside>

## `houseSystem`: lettera, non nome

Sono accettati esattamente questi 25 codici 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`

Maiuscole/minuscole sono significative: `I` è Sunshine di Makransky, `i` è di Trindl. Il nome del sistema (`"Placidus"`, `"Koch"`) restituisce `400`. In precedenza funzionava per caso, perché il motore legge solo la prima lettera dalla stringa, e per lo stesso motivo `"Zodiac"` dava silenziosamente Placidus.

## Ora di nascita sconosciuta

Invece di un mezzogiorno fittizio, passa `timeUnknown: true` e non passare `time`. In questo modo `houses`, `houseAspects`, `chartSect` e `siderealTime` arriveranno `null`, anziché fittizi. Dettagli: [Convenzioni API](/api-conventions/#невідомий-час-народження).

## Chiavi sconosciute non sono rifiutate

Il corpo accetta campi extra silenziosamente: una chiave sconosciuta viene semplicemente ignorata. Pertanto, un errore nel nome di un campo non presente nell'elenco dei rifiuti sopra non si manifesterà. Consulta la specifica: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Avanti

- [Errori comuni](/agent-setup/mistakes/)
- [Insidie](/agent-setup/gotchas/)