# Veldformaten

Een model dat de veldnaam raadt, krijgt of `400`, of, nog erger, een definitief antwoord over een andere kaart. Hieronder de exacte contract.

## Lichaam van het kaartverzoek

| Veld | Type en formaat | Verplicht |
|---|---|---|
| `date` | `YYYY-MM-DD`, en dit moet een echte kalenderdag zijn | ja |
| `time` | `HH:mm:ss` | ja, of `timeUnknown: true` |
| `timezoneOffset` | getal, uren vanaf UTC, bijv. `5.75` | nee, standaard `0` (UTC) |
| `timezone` | IANA zone naam, bijv. `Europe/Kyiv`, of `auto` | nee, en wanneer verzonden, vervangt het `timezoneOffset` |
| `latitude` | decimale graden, noord positief | ja |
| `longitude` | decimale graden, oost positief | ja |
| `houseSystem` | één letter, standaard `P` | nee |
| `city` | string, alleen label | nee |
| `zodiacType` | `tropical` of `sidereal` | nee |

<Aside type="caution">
`city` geocodeert niets. Dit veld is voor een label in je interface, en het **nooit** de coördinaten vervangt.
</Aside>

## Afkortingen worden afgewezen

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` geven `400 INVALID_FIELD` terug met de juiste veldnaam:

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

Hoofdlettergevoeligheid en scheidingstekens zijn niet toegestaan: `TZ_Offset` en `tzoffset` worden evenmin geaccepteerd. **Alle** gevonden velden worden in één keer gerapporteerd, niet alleen de eerste, zodat je ze in één keer kunt corrigeren.

De reden is streng: vóór deze controle gaf een veld dat de API niet las stilzwijgend een offset van `0`, en het antwoord was een definitieve kaart voor UTC. Een verschuiving van drie uur is ongeveer 45° ascendant, dus een ander opkomend teken, zonder enige waarschuwing.

## `timezone`: zone‑naam in plaats van offset

De offset moet die zijn die de klokken **op die specifieke datum** hadden, en handmatig kan die gemakkelijk fout worden opgegeven: Kiev in mei 1990 volgde Moskou zomertijd, UTC+4, niet +3. Stuur `timezone` en de server haalt de offset uit de tijdzone‑database, inclusief zomertijd.

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

- `auto` bepaalt de zone op basis van `latitude` en `longitude`. Dicht bij een grens is de naam nauwkeuriger.
- Als `timezone` en `timezoneOffset` samen worden verzonden, heeft `timezone` voorrang. `input.timezoneOffset` in het antwoord toont de gebruikte offset.
- Tijd die twee keer voorkwam (wanneer de klokken teruggingen) wordt genomen bij de eerste keer. Tijd die ontbrak (wanneer de klokken vooruit gingen) krijgt de offset die gold vóór de overgang.
- Zonder `time` (alleen datum of `timeUnknown: true`) wordt de zone gelezen op de lokale middag.
- Wordt afgewezen met `400 INVALID_FIELD`: lege waarde, afkortingen zoals `EST` of `PST`, offset geschreven als tekst, zoals `+03:00`, namen die niet in de database staan, en `auto` zonder coördinaten. `UTC` en `GMT` worden geaccepteerd.
- Elk object wordt afzonderlijk verwerkt, dus `chart1` en `chart2` kunnen in verschillende zones staan.

<Aside type="note">
Tot 1970 is de tijdzone‑database niet betrouwbaar voor elke locatie: Amsterdam in juni 1930 wordt geretourneerd als +1, hoewel de klokken +0:20 toonden. Als de lokale tijd van die geboorte bekend is, stuur dan `timezoneOffset`.
</Aside>

## `houseSystem`: letter, geen naam

Exact deze 25 codes van Swiss Ephemeris worden geaccepteerd:

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

Hoofdlettergevoeligheid is belangrijk: `I` is Sunshine volgens McRansky, `i` volgens Trundle. Een systeemnaam (`"Placidus"`, `"Koch"`) geeft `400`. Voorheen werkte het willekeurig, omdat de engine alleen de eerste letter van de string leest, en om die reden gaf `"Zodiac"` stilzwijgend Placidus.

## Onbekende geboortetijd

In plaats van een verzonnen middag, stuur `timeUnknown: true` en stuur geen `time`. Dan komen `houses`, `houseAspects`, `chartSect` en `siderealTime` als `null` terug, niet verzonnen. Details: [API-conventies](/api-conventions/#невідомий-час-народження).

## Onbekende sleutels worden niet afgewezen

Het lichaam accepteert stilzwijgend extra velden: een onbekende sleutel wordt simpelweg genegeerd. Daarom zal een fout in een veldnaam die niet in de bovenstaande afwijzingslijst staat, niet opgemerkt worden. Raadpleeg de specificatie: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Verder

- [Typische fouten](/agent-setup/mistakes/)
- [Valstrikken](/agent-setup/gotchas/)