Formati dei campi

Last updated 18 set 2026 Apri come Markdown Configurazione agente

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

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:

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

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

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

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.

Avanti