Formats de champs

Un modèle qui devine le nom d’un champ reçoit soit un 400, soit, pire encore, une réponse confiante pour une carte différente. Voici le contrat exact.

Corps de la requête de carte

Champ	Type et format	Obligatoire
date	YYYY-MM-DD, et ce doit être un jour de calendrier réel	oui
time	HH:mm:ss	oui, ou timeUnknown: true
timezoneOffset	nombre, heures depuis UTC, ex. 5.75	non, par défaut 0 (UTC)
timezone	nom de zone IANA, ex. Europe/Kyiv, ou auto	non, et si envoyé, remplace timezoneOffset
latitude	degrés décimaux, nord positif	oui
longitude	degrés décimaux, est positif	oui
houseSystem	une seule lettre, par défaut P	non
city	chaîne de caractères, signature uniquement	non
zodiacType	tropical ou sidereal	non

Attention

city ne géocode rien. C’est un champ pour la signature dans ton interface, et il ne remplace jamais les coordonnées.

Les abréviations sont rejetées

lat, lon, lng, long, tz, tzOffset, utcOffset, gmtOffset, timeZone, time_zone renvoient un 400 INVALID_FIELD avec le nom du champ correct :

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

La casse et les séparateurs n’ont pas d’importance : TZ_Offset et tzoffset sont rejetés de la même manière. Tous les champs trouvés sont signalés immédiatement, et non le premier, afin que tu puisses corriger en une seule fois.

La raison est stricte : avant cette validation, un champ non lu par l’API donnait silencieusement un décalage de 0, et la réponse était une carte confiante pour l’UTC. Trois heures de décalage représentent environ 45° d’ascendant, c’est-à-dire un signe ascendant différent, et aucun avertissement.

timezone : nom de la zone au lieu du décalage

Le décalage doit être celui qu’indiquaient les horloges à cette date précise, et il est facile de le spécifier manuellement de manière incorrecte : Kiev en mai 1990 vivait à l’heure d’été de Moscou, UTC+4, et non +3. Envoie timezone, et le serveur prendra le décalage de la base de données des fuseaux horaires, y compris l’heure d’été.

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

• auto détermine la zone en fonction de latitude et longitude. Près d’une frontière, le nom est plus précis.
• Si timezone et timezoneOffset sont envoyés ensemble, timezone est prioritaire. input.timezoneOffset dans la réponse indique le décalage qui a été utilisé.
• L’heure qui a eu lieu deux fois (lorsque les horloges ont été reculées) est prise la première fois. L’heure qui n’a pas eu lieu (lorsque les horloges ont été avancées) reçoit le décalage qui était en vigueur avant le changement.
• Sans time (seulement la date ou timeUnknown: true), la zone est lue pour le midi local.
• Sont rejetés avec un 400 INVALID_FIELD : valeur vide, abréviations comme EST ou PST, décalage écrit en texte comme +03:00, noms qui ne sont pas dans la base de données, et auto sans coordonnées. UTC et GMT sont acceptés.
• Chaque objet est analysé séparément, donc chart1 et chart2 peuvent être dans des zones différentes.

Note

Avant 1970, la base de données des fuseaux horaires n’est pas fiable pour chaque lieu : Amsterdam en juin 1930 est renvoyé comme +1, bien que les horloges indiquaient +0:20. Si l’heure locale de cette naissance est connue, envoie timezoneOffset.

houseSystem : lettre, pas un nom

Seuls ces 25 codes Swiss Ephemeris sont acceptés :

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

La casse est significative : I est Sunshine selon Makransky, i selon Trindl. Le nom du système ("Placidus", "Koch") renvoie un 400. Auparavant, cela fonctionnait par hasard, car le moteur ne lit que la première lettre de la chaîne, et pour la même raison, "Zodiac" donnait silencieusement Placidus.

Heure de naissance inconnue

Au lieu d’un midi inventé, transmets timeUnknown: true et ne transmets pas time. Alors houses, houseAspects, chartSect et siderealTime seront null, et non inventés. Détails : Conventions de l’API.

Les clés inconnues ne sont pas rejetées

Le corps accepte les champs superflus silencieusement : une clé inconnue est simplement ignorée. Par conséquent, une erreur dans le nom d’un champ qui n’est pas dans la liste des rejets ci-dessus ne se manifestera pas. Référe-toi à la spécification : /v1/openapi.json.

Suite

• Erreurs courantes
• Pièges