API de mapa natal

URL base: https://api.natalchart.ai. Toda requisição leva uma chave de API, toda resposta é em JSON e toda longitude vem com quatro casas decimais de grau antes de ser convertida em signo. A chave é grátis: entre com uma conta do NatalChart.AI e crie uma.

Início rápido

curl https://api.natalchart.ai/v1/chart/short \
  -H "Authorization: Bearer $NATALCHART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":{"date":"1991-09-06","time":"18:30","latitude":50.4501,"longitude":30.5234}}'

A resposta, para o nascimento de demonstração usado em todo o site (1991-09-06, 18:30, Kiev). São mostrados cinco dos corpos:

{
  "sun": {
    "sign": "Virgo",
    "degreeInSign": 13.55,
    "house": 7
  },
  "moon": {
    "sign": "Leo",
    "degreeInSign": 19.02,
    "house": 7
  },
  "ascendant": {
    "sign": "Aquarius",
    "degreeInSign": 14.9898
  },
  "signs": {
    "Sun": "Virgo",
    "Moon": "Leo",
    "Mercury": "Leo",
    "Venus": "Leo",
    "Mars": "Libra"
  },
  "retrograde": [
    "Venus",
    "Saturn",
    "Uranus",
    "Neptune",
    "TrueNode",
    "Lilith",
    "Juno"
  ]
}

Servidor MCP para assistentes de IA

Os mesmos cálculos estão disponíveis como servidor MCP em https://www.natalchart.ai/mcp, para Claude, ChatGPT, Cursor e VS Code. Ele usa a mesma chave e gasta a mesma cota diária, uma requisição por chamada de ferramenta. A configuração de cada cliente está em Servidor MCP para assistentes de IA.

Autenticação

Envie a chave como Authorization: Bearer nc_live_... (um cabeçalho X-API-Key também funciona). A chave completa aparece uma única vez, quando você a cria; guardamos apenas o hash dela. Uma conta pode ter até cinco chaves ativas e revogar qualquer uma delas na hora. Mantenha as chaves num servidor: uma chave incluída no código de um navegador ou de um app pode ser lida por qualquer pessoa.

Dados de nascimento

Os endpoints que calculam um mapa recebem um objeto:

{
  "birth": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timezone": "Europe/Kyiv"
  }
}

Endpoints

O mapa completo

POST /v1/chart/full retorna o cálculo inteiro no formato do arquivo de demonstração publicado, para que você possa conferir uma resposta com um mapa fixo antes de escrever qualquer código. Aqui, reduzido a dois corpos, duas cúspides e os dois aspectos mais exatos:

{
  "input": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timeKnown": true
  },
  "time": {
    "timezone": "Europe/Kyiv",
    "offsetHours": 3,
    "julianDayUT": 2448506.1458333335
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 163.5457,
      "sign": "Virgo",
      "degreeInSign": 13.55,
      "speed": 0.9704,
      "retrograde": false,
      "house": 7
    },
    {
      "name": "Moon",
      "longitude": 139.0225,
      "sign": "Leo",
      "degreeInSign": 19.02,
      "speed": 14.5955,
      "retrograde": false,
      "house": 7
    }
  ],
  "angles": {
    "ascendant": {
      "longitude": 314.9898,
      "sign": "Aquarius"
    },
    "midheaven": {
      "longitude": 249.8956,
      "sign": "Sagittarius"
    }
  },
  "houses": [
    {
      "number": 1,
      "cusp": 314.9898,
      "sign": "Aquarius"
    },
    {
      "number": 2,
      "cusp": 13.7492,
      "sign": "Aries"
    }
  ],
  "aspects": [
    {
      "planet1": "Pallas",
      "planet2": "Juno",
      "aspect": "Square",
      "angle": 89.79,
      "orb": 0.21,
      "phase": "separating"
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43,
      "phase": "separating"
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

Os endpoints de segmento (planets, angles, houses, aspects, elements, fixed-stars) retornam, cada um, uma parte do mesmo objeto, para quem precisa só dessa parte.

O horóscopo diário

POST /v1/horoscope/daily é a metade calculada de um horóscopo diário: o céu ao meio-dia UTC, a fase e o signo da Lua, os eventos do céu dos próximos sete dias e, quando você envia birth, cada trânsito sobre esse mapa com seu aspecto, seu orbe, se está em aplicação ou em separação, o momento em que é ou foi exato e a casa natal em que está o corpo em trânsito. Os orbes de trânsito são de 2° para a Lua, o Sol, Mercúrio, Vênus e Marte e de 3° para os corpos mais lentos. Dois campos são regras fixas, não astronomia, e a resposta deixa isso claro: tone (supportive para trígono e sextil, challenging para quadratura e oposição, intensifying para conjunção) e focus, os três contatos mais bem classificados pela velocidade do planeta e pela exatidão do aspecto. Não há texto escrito; essa parte é sua.

Uma resposta real para o mapa de demonstração no dia 2026-09-18, com as listas reduzidas a dois itens:

{
  "date": "2026-09-18",
  "computedFor": "2026-09-18T12:00:00.000Z",
  "moon": {
    "phase": "First Quarter",
    "illumination": 46.5,
    "elongation": 86.04,
    "sign": "Sagittarius",
    "longitude": 261.6344,
    "degreeInSign": 21.63,
    "theme": "Decision + Action",
    "nextNewMoon": {
      "utc": "2026-10-10T15:50:05.436Z",
      "sign": "Libra",
      "degreeInSign": 17.36,
      "absoluteDegree": 197.36
    },
    "nextFullMoon": {
      "utc": "2026-09-26T16:49:02.781Z",
      "sign": "Aries",
      "degreeInSign": 3.62,
      "absoluteDegree": 3.62
    }
  },
  "positions": [
    {
      "name": "Sun",
      "longitude": 175.5994,
      "sign": "Virgo",
      "degreeInSign": 25.6,
      "speed": 0.9761,
      "retrograde": false
    },
    {
      "name": "Moon",
      "longitude": 261.6344,
      "sign": "Sagittarius",
      "degreeInSign": 21.63,
      "speed": 11.8869,
      "retrograde": false
    }
  ],
  "events": [
    {
      "kind": "ingress",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    },
    {
      "kind": "equinox",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    }
  ],
  "transits": [
    {
      "transit": "Vesta",
      "natal": "Mercury",
      "aspect": "Trine",
      "angle": 119.93,
      "orb": 0.07,
      "phase": "applying",
      "exactAt": "2026-09-18T21:43:39.997Z",
      "tone": "supportive",
      "transitHouse": 2,
      "houseTheme": "Money & Possessions"
    },
    {
      "transit": "Uranus",
      "natal": "Lilith",
      "aspect": "Trine",
      "angle": 119.86,
      "orb": 0.14,
      "phase": "separating",
      "exactAt": null,
      "tone": "supportive",
      "transitHouse": 3,
      "houseTheme": "Communication & Learning"
    }
  ],
  "focus": [
    {
      "transit": "Pluto",
      "natal": "Mars",
      "aspect": "Trine",
      "angle": 119.78,
      "orb": 0.22,
      "phase": "separating",
      "exactAt": "2026-09-03T17:58:04.996Z",
      "tone": "supportive",
      "transitHouse": 12,
      "houseTheme": "Spirituality & Subconscious"
    },
    {
      "transit": "Neptune",
      "natal": "Mars",
      "aspect": "Opposition",
      "angle": 179.74,
      "orb": 0.26,
      "phase": "separating",
      "exactAt": "2026-09-09T00:24:29.005Z",
      "tone": "challenging",
      "transitHouse": 1,
      "houseTheme": "Identity & Self"
    },
    {
      "transit": "Jupiter",
      "natal": "Moon",
      "aspect": "Conjunction",
      "angle": 1.77,
      "orb": 1.77,
      "phase": "applying",
      "exactAt": "2026-09-27T20:40:07.004Z",
      "tone": "intensifying",
      "transitHouse": 7,
      "houseTheme": "Partnerships & Marriage"
    }
  ]
}

Endpoints do API Pro

Seis endpoints que, juntos, são tudo o que o app calcula. Cada exemplo abaixo é uma resposta real para o mapa de demonstração, resumida; "..." numa requisição representa o objeto de dados de nascimento mostrado acima.

Trânsitos de um período

POST /v1/transits recebe birth, from e to (no máximo 92 dias) e retorna, por data, cada aspecto exato de trânsito sobre o mapa natal, cada ingresso em signo e cada estação no período, além dos contatos ativos no primeiro dia com a fase e o momento exato de cada um.

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "date": "2026-09-19",
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-22",
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-23",
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-26",
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "significance": "low"
    }
  ]
}

Sinastria

POST /v1/synastry recebe personA e personB e retorna os aspectos entre mapas com orbes, em que casas da outra pessoa caem os planetas de cada uma e uma pontuação para cada uma das seis esferas da vida. Aqui a segunda pessoa também é fictícia (1989-03-14, 07:45, Nova York).

{
  "aspects": [
    {
      "personA": "Neptune",
      "personB": "Lilith",
      "aspect": "Trine",
      "angle": 120.08,
      "orb": 0.08
    },
    {
      "personA": "Saturn",
      "personB": "Jupiter",
      "aspect": "Trine",
      "angle": 119.66,
      "orb": 0.34
    },
    {
      "personA": "Mercury",
      "personB": "Moon",
      "aspect": "Sextile",
      "angle": 60.38,
      "orb": 0.38
    }
  ],
  "sphereScores": {
    "identity": 89,
    "love": 81,
    "body": 86,
    "money": 76,
    "home": 83,
    "mind": 66
  }
}

Revolução solar

POST /v1/solar-return recebe birth, year e location (opcional) e retorna o momento exato em que o Sol volta à sua longitude natal, com o mapa completo calculado para esse momento. Ele precisa da hora de nascimento: sem ela, o Sol natal tem uma incerteza de meio grau, o que desloca a revolução em cerca de doze horas.

{
  "year": 2027,
  "exactMomentUtc": "2027-09-06T08:29:55Z",
  "location": {
    "latitude": 50.4501,
    "longitude": 30.5234
  },
  "chart": "the full chart of that moment, in the shape of /v1/chart/full"
}

Melhores dias para uma atividade

POST /v1/timing recebe birth, activity (general, business, romance, health, creative, travel, home ou clarity), from e to (no máximo 62 dias) e timezone (opcional), que define onde cada dia começa. Cada dia recebe uma pontuação de 0 a 100 a partir da geometria exata dos trânsitos, ponderada pelos planetas que importam para a atividade, e os cinco melhores dias vêm primeiro. Ele descreve o céu; não promete como será o dia.

{
  "activity": "business",
  "best": [
    {
      "date": "2026-10-12",
      "score": 69.5,
      "rating": "good",
      "moonPhase": "New Moon",
      "moonSign": "Scorpio",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Moon (0.2°)",
        "Transit Mercury Sextile Sun (0.3°)",
        "Transit Mercury Sextile Neptune (0.2°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.8°)"
      ]
    },
    {
      "date": "2026-10-14",
      "score": 63.5,
      "rating": "good",
      "moonPhase": "Waxing Crescent",
      "moonSign": "Sagittarius",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Venus (1.1°)",
        "Transit Moon Sextile Saturn (0.7°)",
        "Transit Jupiter Conjunction Venus (0.1°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.7°)",
        "Transit Saturn Square Uranus (0.6°)"
      ]
    }
  ]
}

Um lugar comparado a um mapa

POST /v1/locations/score recebe birth e location com coordenadas. O mapa é relocado para lá, e a resposta traz os ângulos relocados, os planetas sobre eles com seus orbes, uma pontuação de 0 a 10 para cada esfera da vida (5 é neutro) e a intensidade com que o mapa reage ao lugar: forte quando um planeta principal está a até 2° de um ângulo, moderada a até 4°, fraca nos demais casos.

{
  "relocated": {
    "ascendant": {
      "longitude": 277.7847,
      "sign": "Capricorn"
    },
    "midheaven": {
      "longitude": 210.708,
      "sign": "Scorpio"
    }
  },
  "angularPlanets": [
    {
      "planet": "Uranus",
      "angle": "ASC",
      "orb": 2.12,
      "weight": "major",
      "strength": "strong"
    },
    {
      "planet": "Neptune",
      "angle": "ASC",
      "orb": 6.31,
      "weight": "major",
      "strength": "weak"
    }
  ],
  "spheres": {
    "identity": {
      "score10": 1,
      "verdict": "challenging"
    },
    "love": {
      "score10": 6.1,
      "verdict": "slightly supportive"
    },
    "body": {
      "score10": 3.2,
      "verdict": "challenging"
    },
    "money": {
      "score10": 2.2,
      "verdict": "challenging"
    },
    "home": {
      "score10": 1.7,
      "verdict": "challenging"
    },
    "mind": {
      "score10": 4.9,
      "verdict": "neutral"
    }
  },
  "overall10": 2.2,
  "strength": "moderate"
}

As melhores cidades para um mapa

POST /v1/locations/rank recebe birth, focus (opcional, qualquer um de identity, love, body, money, home, mind), region (opcional) e limit, de 3 a 12, e classifica um catálogo de 61 grandes cidades. Nem todas as cidades da Terra são comparadas; qualquer outro lugar pode ser pontuado com o endpoint acima.

{
  "comparedCities": 61,
  "top": [
    {
      "city": "New York",
      "country": "United States",
      "overall10": 7.4,
      "focus10": 8.3,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.6°",
        "Moon MC 2.3°"
      ]
    },
    {
      "city": "Tbilisi",
      "country": "Georgia",
      "overall10": 7.4,
      "focus10": 8.2,
      "strength": "moderate",
      "contacts": [
        "Sun DSC 3.3°"
      ]
    },
    {
      "city": "Montreal",
      "country": "Canada",
      "overall10": 7.4,
      "focus10": 8.1,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.1°",
        "Moon MC 2.8°",
        "Mercury MC 3.8°"
      ]
    }
  ]
}

Limites e preços

As requisições são contadas por conta, somando todas as suas chaves, e a cota se renova às 00:00 UTC. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma requisição rejeitada por ser inválida não é contada, um cálculo que falha do nosso lado é devolvido à cota e GET /v1/usage é sempre grátis. O API Pro é uma assinatura separada dos planos do app: não inclui o Premium do app, e o Premium do app não o inclui. As duas cotas também são separadas: o app conta as respostas de IA por semana, esta API conta os cálculos por dia UTC, e uma não consome a outra.

Erros

Todo erro tem o mesmo formato: { "error": { "code", "message", "details"?, "docs" } }.

Configurações de cálculo

Elas são fixas e são as configurações do próprio app, descritas em detalhe na página Verifique seu mapa e conferidas com o NASA JPL Horizons no relatório de precisão. Arquivos de dados do Swiss Ephemeris com o indicador de velocidade ativado. Zodíaco tropical, posições geocêntricas e aparentes. Casas Placidus. Nodo lunar verdadeiro. Lilith como apogeu lunar osculador. Parte da Fortuna como ASC + Lua − Sol, igual para mapas diurnos e noturnos. Apenas os cinco aspectos maiores: conjunção 8°, sextil 6°, quadratura 8°, trígono 8°, oposição 8°. Cada aspecto natal e de trânsito indica se está em aplicação ou em separação, a partir das velocidades dos dois corpos, incluindo o movimento retrógrado.

Privacidade

Dados de nascimento são dados pessoais. A API os lê, calcula, responde e os esquece: nenhum corpo de requisição é armazenado, e nada do que você envia é usado para outra coisa além da resposta. De cada requisição guardamos o endpoint, o código de status e a latência. Veja a política de privacidade.

Perguntas