Formats de champs

Un modèle qui devine le nom du champ retourne soit 400, soit, pire encore, une réponse confiante concernant une autre carte. Voici le contrat précis ci-dessous.

Corps de la requête de carte

Champ	Type et format	Obligatoire
date	YYYY-MM-DD, et cela doit être une date réelle du calendrier	Oui
time	HH:mm:ss	Oui, ou timeUnknown: true
timezoneOffset	nombre, heures depuis UTC, par exemple 5.75	Non, généralement 0 (UTC)
timezone	nom de la zone IANA, par exemple Europe/Kyiv, ou auto	Non, et quand envoyé, remplace timezoneOffset
latitude	degrés décimaux, positif pour le nord	Oui
longitude	degrés décimaux, positif pour l’est	Oui
houseSystem	une lettre, généralement P	Non
city	chaîne, uniquement pour l’affichage	Non
zodiacType	tropical ou sidereal	Non

Attention

city ne géocode rien. Ce champ est pour l’affichage dans votre interface, et il jamais remplace les coordonnées. Pour obtenir les coordonnées et la ville à partir d’un nom, appelez d’abord GET /v1/geo/search (Recherche de lieux).

Les abréviations courtes sont rejetées

lat, lon, lng, long, tz, tzOffset, utcOffset, gmtOffset, timeZone, time_zone retournent 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 des valeurs 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, pour que la correction puisse être faite en une seule fois.

La raison est stricte : avant cette vérification, un champ que l’API ne lisait pas donnait silencieusement un décalage de 0, et la réponse était une carte confiante pour UTC. Trois heures de décalage correspondent environ à 45° d’ascendant, soit un autre signe levant, sans aucun avertissement.

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

Le décalage doit être celui que montraient les horloges exactement à cette date, et il est facile de le spécifier manuellement à tort : Kiev en mai 1990 vivait selon l’heure d’été de Moscou, UTC+4, et non +3. Envoyez timezone, et le serveur prendra le décalage depuis 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 à partir de latitude et longitude. Près des frontières, le nom est plus précis.
• Si timezone et timezoneOffset sont envoyés ensemble, timezone l’emporte. input.timezoneOffset dans la réponse montre le décalage utilisé.
• Pour les heures qui ont eu lieu deux fois (lorsque les horloges ont été remises à l’heure), on prend la première occurrence. Pour les heures qui n’ont pas eu lieu (lorsque les horloges ont été avancées), on utilise le décalage qui était en vigueur avant l’avancement.
• Sans time (seulement la date ou timeUnknown: true), la zone est lue à midi local.
• Les erreurs 400 INVALID_FIELD sont retournées pour : une valeur vide, des abréviations comme EST ou PST, un décalage écrit sous forme textuelle comme +03:00, des noms inexistants dans la base de données, et auto sans coordonnées. UTC et GMT sont acceptés.
• Chaque objet est traité 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 retourné comme +1, alors que les horloges montraient +0:20. Si l’heure locale de cette naissance est connue, envoyez timezoneOffset.

houseSystem : une lettre, pas un nom

Seulement ces 25 codes à une lettre sont acceptés (les mêmes que dans swetest) :

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 Macransky, i selon Trigndle. Le nom du système ("Placidus", "Koch") retourne 400. Avant, cela fonctionnait par hasard, car le moteur ne lisait 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’une heure inventée, envoyez timeUnknown: true et ne transmettez pas time. Alors houses, houseAspects, chartSect et siderealTime arrivent null, et non des valeurs inventées. Détails : Conventions de l’API.

Clés inconnues non rejetées

Le corps accepte silencieusement les champs supplémentaires : une clé inconnue est simplement ignorée. Ainsi, une erreur dans le nom d’un champ qui n’est pas dans la liste des rejets ci-dessus ne se signalera pas. Vérifiez la spécification : /v1/openapi.json.

Suite

• Erreurs courantes
• Pièges