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

Opgepast

city geocodeert niets. Dit veld is voor een label in je interface, en het nooit de coördinaten vervangt.

Afkortingen worden afgewezen

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

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

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

Opmerking

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.

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.

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.

Verder

• Typische fouten
• Valstrikken