Formatos de campos

O modelo que tenta adivinhar o nome do campo recebe ou 400 ou, pior ainda, uma resposta confiante sobre outra carta. Abaixo está o contrato exato.

Corpo da solicitação de carta

Campo	Tipo e formato	Obrigatório
date	YYYY-MM-DD, e deve ser um dia calendário real	sim
time	HH:mm:ss	sim, ou timeUnknown: true
timezoneOffset	número, horas em relação ao UTC, por exemplo 5.75	não, padrão 0 (UTC)
timezone	nome da zona IANA, por exemplo Europe/Kyiv, ou auto	não, e quando enviado, substitui timezoneOffset
latitude	graus decimais, norte positivo	sim
longitude	graus decimais, leste positivo	sim
houseSystem	uma letra, padrão P	não
city	string, apenas assinatura	não
zodiacType	tropical ou sidereal	não

Cuidado

city não faz geocodificação nenhuma. Este campo é para uma assinatura na sua interface, e ele nunca substitui as coordenadas.

Formas abreviadas são rejeitadas

lat, lon, lng, long, tz, tzOffset, utcOffset, gmtOffset, timeZone, time_zone retornam 400 INVALID_FIELD com o nome do campo correto:

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

Regra e separadores no valor não importam: TZ_Offset e tzoffset são rejeitados da mesma forma. Todos os campos encontrados são relatados de uma vez, não apenas o primeiro, para que você possa corrigi-los de uma só vez.

Motivo da rigidez: antes desta verificação, um campo que a API não lia dava silenciosamente um deslocamento de 0, e a resposta era uma carta confiante para UTC. Três horas de deslocamento correspondem aproximadamente a 45° de ascendente, ou seja, outro signo a nascer, e nenhum aviso.

timezone: nome da zona em vez do deslocamento

O deslocamento deve ser aquele que os relógios estavam realmente a marcar nessa data, e é fácil indicá-lo incorretamente à mão: Kiev em maio de 1990 estava no horário de verão de Moscovo, UTC+4, não +3. Envie timezone, e o servidor irá obter o deslocamento da base de dados de fusos horários, incluindo o horário de verão.

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

• auto determina a zona com base em latitude e longitude. Perto da fronteira, o nome é mais preciso.
• Se timezone e timezoneOffset chegarem juntos, timezone tem precedência. input.timezoneOffset na resposta mostra o deslocamento que foi utilizado.
• O horário que ocorreu duas vezes (quando os relógios foram atrasados) é considerado na primeira ocorrência. O horário que não ocorreu (quando os relógios foram adiantados) recebe o deslocamento que estava em vigor antes da mudança.
• Sem time (apenas data ou timeUnknown: true) a zona é lida ao meio-dia local.
• Rejeitado com 400 INVALID_FIELD: valor vazio, abreviações como EST ou PST, deslocamento escrito como texto, como +03:00, nomes que não estão na base de dados, e auto sem coordenadas. UTC e GMT são aceites.
• Cada objeto é analisado separadamente, portanto chart1 e chart2 podem estar em zonas diferentes.

Nota

Antes de 1970 a base de dados de fusos horários não é fiável para todos os locais: Amsterdão em junho de 1930 retorna +1, embora os relógios marcassem +0:20. Se o horário local do nascimento for conhecido, envie timezoneOffset.

houseSystem: letra, não nome

Exatamente estes 25 códigos da Swiss Ephemeris são aceites:

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

A maiúscula/minúscula importa: I é Sunshine por McCranky, i por Traindl. O nome do sistema ("Placidus", "Koch") retorna 400. Antes funcionava por acaso, pois o motor lê apenas a primeira letra da string, e por esse mesmo motivo "Zodiac" dava silenciosamente Placidus.

Tempo de nascimento desconhecido

Em vez de fabricar um meio-dia, envie timeUnknown: true e não envie time. Então houses, houseAspects, chartSect e siderealTime chegam como null, não fabricados. Detalhes: Convenções da API.

Chaves desconhecidas não são rejeitadas

O corpo aceita campos extras silenciosamente: uma chave desconhecida é simplesmente ignorada. Portanto, um erro no nome de um campo que não está na lista de rejeição acima passará despercebido. Verifique-se com a especificação: /v1/openapi.json.

Seguinte

• Erros comuns
• Armadilhas