Formatos de campos

Um modelo que adivinha o nome do campo retorna ou 400, ou, pior ainda, uma resposta confiante sobre outro mapa. Abaixo está o contrato exato.

Corpo da requisição do mapa

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

Cuidado

city não faz geocoding. Esse campo é apenas para descrição na sua interface e nunca substitui as coordenadas. Para obter coordenadas e fuso horário a partir do nome, primeiro chame GET /v1/geo/search (Busca de Locais).

Abreviações curtas 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)." } }

A caixa alta e os separadores dos valores não importam: TZ_Offset e tzoffset são rejeitados da mesma forma. Todos os campos encontrados são relatados de uma vez, e não apenas o primeiro, para que possam ser corrigidos em um único passo.

A razão é rigorosa: antes dessa verificação, um campo que o API não lia silenciosamente atribuía um deslocamento de 0, e a resposta era um mapa confiante para UTC. Três horas de deslocamento equivalem a cerca de 45° de ascendente, ou seja, um signo diferente nascendo, sem nenhum aviso.

timezone: nome da zona em vez do deslocamento

O deslocamento deve ser o que os relógios exatamente naquela data estavam mostrando, e é fácil errar ao inseri-lo manualmente: Kiev em maio de 1990 estava no horário de verão de Moscou, UTC+4, e não +3. Envie timezone, e o servidor pegará 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. Próximo à fronteira, o nome é mais preciso.
• Se timezone e timezoneOffset forem enviados juntos, prevalece timezone. input.timezoneOffset na resposta mostra o deslocamento que foi usado.
• O horário que ocorreu duas vezes (quando os relógios foram atrasados) é considerado pela primeira vez. O horário que não ocorreu (quando foram adiantados) recebe o deslocamento que estava em vigor antes do ajuste.
• Sem time (apenas data ou timeUnknown: true) a zona é lida para o meio-dia local.
• São rejeitados com 400 INVALID_FIELD: valor vazio, abreviações como EST ou PST, deslocamento escrito como texto, como +03:00, nomes que não existem na base de dados, e auto sem coordenadas. UTC e GMT são aceitos.
• Cada objeto é processado individualmente, então chart1 e chart2 podem estar em zonas diferentes.

Nota

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

houseSystem: letra, não nome

São aceitos exatamente esses 25 códigos de uma letra (os mesmos que no 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

A caixa alta é significativa: I é Sunshine por Macransky, i por Trigndle. O nome do sistema ("Placidus", "Koch") retorna 400. Antes, isso funcionava por acaso, porque o motor lê apenas a primeira letra da string, e por essa mesma razão "Zodiac" silenciosamente retornava Placidus.

Hora de nascimento desconhecida

Em vez de um meio-dia inventado, envie timeUnknown: true e não envie time. Assim, houses, houseAspects, chartSect e siderealTime chegam como null, e não como valores inventados. 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ções acima não será notado. Confira a especificação: /v1/openapi.json.

Próximo

• Erros comuns
• Armadilhas