Geburtshoroskop-API

Basis-URL: https://api.natalchart.ai. Jede Anfrage enthält einen API-Schlüssel, jede Antwort ist JSON, und jede Länge wird mit vier Nachkommastellen in Grad angegeben, bevor daraus ein Zeichen wird. Der Schlüssel ist kostenlos: Melde dich mit einem NatalChart.AI-Konto an und erstelle einen.

Schnellstart

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}}'

Die Antwort für die Demo-Geburtsdaten, die auf dieser ganzen Website verwendet werden (1991-09-06, 18:30, Kyjiw). Gezeigt werden fünf der Himmelskörper:

{
  "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"
  ]
}

MCP-Server für KI-Assistenten

Dieselben Berechnungen gibt es als MCP-Server unter https://www.natalchart.ai/mcp, für Claude, ChatGPT, Cursor und VS Code. Er nimmt denselben Schlüssel an und verbraucht dasselbe Tageskontingent, eine Anfrage pro Tool-Aufruf. Die Einrichtung für jeden Client: MCP-Server für KI-Assistenten.

Authentifizierung

Sende den Schlüssel als Authorization: Bearer nc_live_... (ein Header X-API-Key funktioniert ebenfalls). Der vollständige Schlüssel wird ein einziges Mal angezeigt, wenn du ihn erstellst; wir speichern nur seinen Hash. Ein Konto kann bis zu fünf aktive Schlüssel haben und jeden davon sofort widerrufen. Bewahre Schlüssel auf einem Server auf: Ein Schlüssel, der im Browser- oder App-Code ausgeliefert wird, kann von jedem gelesen werden.

Geburtsdaten

Endpunkte, die ein Horoskop berechnen, erwarten ein Objekt:

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

Endpunkte

Das vollständige Horoskop

POST /v1/chart/full liefert die ganze Berechnung in der Struktur der veröffentlichten Demo-Datei, sodass du eine Antwort mit einem festen Horoskop abgleichen kannst, bevor du Code schreibst. Hier gekürzt auf zwei Himmelskörper, zwei Häuserspitzen und die zwei engsten Aspekte:

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

Die Segment-Endpunkte (planets, angles, houses, aspects, elements, fixed-stars) liefern jeweils einen Teil desselben Objekts, für Aufrufer, die nur diesen Teil brauchen.

Das Tageshoroskop

POST /v1/horoscope/daily ist die berechnete Hälfte eines Tageshoroskops: der Himmel um 12:00 Uhr UTC, Phase und Zeichen des Mondes, die Himmelsereignisse der kommenden Woche und, wenn du birth mitsendest, jeder Transit zu diesem Horoskop mit seinem Aspekt, seinem Orbis, der Angabe, ob er applikativ (sich bildend) oder separativ (sich lösend) ist, dem Moment, in dem er exakt ist oder war, und dem Haus des Geburtshoroskops, in dem der transitierende Himmelskörper steht. Die Transitorben betragen 2° für Mond, Sonne, Merkur, Venus und Mars und 3° für die langsameren Himmelskörper. Zwei Felder sind feste Regeln statt Astronomie, und die Antwort nennt sie: tone (supportive für Trigon und Sextil, challenging für Quadrat und Opposition, intensifying für Konjunktion) und focus, die drei Kontakte, die nach Geschwindigkeit des Planeten und Enge am höchsten eingestuft werden. Einen geschriebenen Text gibt es nicht: Dieser Teil liegt bei dir.

Eine echte Antwort für das Demo-Horoskop am 2026-09-18, die Listen auf je zwei Einträge gekürzt:

{
  "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"
    }
  ]
}

Endpunkte von API Pro

Sechs Endpunkte, zusammen alles, was die App berechnet. Jedes Beispiel unten ist eine echte, gekürzte Antwort für das Demo-Horoskop; "..." in einer Anfrage steht für das oben gezeigte Objekt mit den Geburtsdaten.

Transite für einen Zeitraum

POST /v1/transits erwartet birth, from und to (höchstens 92 Tage) und liefert jeden exakten Transitaspekt zum Geburtshoroskop nach Datum, jeden Zeichenwechsel und jeden Stillstand im Zeitraum, dazu die am ersten Tag aktiven Kontakte mit ihrer Phase und ihrem exakten Moment.

{
  "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"
    }
  ]
}

Synastrie

POST /v1/synastry erwartet personA und personB und liefert die Aspekte zwischen den Horoskopen mit Orben, in welche Häuser der jeweils anderen Person die Planeten jeder Person fallen, und einen Wert für jeden der sechs Lebensbereiche. Die zweite Person ist hier ebenfalls fiktiv (1989-03-14, 07:45, New 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
  }
}

Solarhoroskop

POST /v1/solar-return erwartet birth, year und optional location und liefert den exakten Moment, in dem die Sonne zu ihrer Länge im Geburtshoroskop zurückkehrt, mit dem vollständigen Horoskop für diesen Moment. Dafür ist eine Geburtszeit nötig: Ohne sie ist die Sonne des Geburtshoroskops um einen halben Grad unsicher, was die Rückkehr um etwa zwölf Stunden verschiebt.

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

Die besten Tage für eine Aktivität

POST /v1/timing erwartet birth, activity (general, business, romance, health, creative, travel, home oder clarity), from und to (höchstens 62 Tage) und optional timezone, das festlegt, wann jeder Tag beginnt. Jeder Tag erhält aus der exakten Transitgeometrie einen Wert von 0 bis 100, gewichtet nach den Planeten, die für die Aktivität zählen, und die fünf besten Tage stehen vorn. Der Endpunkt beschreibt den Himmel; er verspricht keinen Tag.

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

Ein Ort, gemessen an einem Horoskop

POST /v1/locations/score erwartet birth und location mit Koordinaten. Das Horoskop wird auf diesen Ort umgerechnet, und die Antwort nennt die umgerechneten Achsen, die Planeten darauf mit ihren Orben, einen Wert von 0 bis 10 für jeden Lebensbereich (5 ist neutral) und wie stark das Horoskop überhaupt auf den Ort reagiert: stark, wenn ein wichtiger Planet innerhalb von 2° einer Achse steht, mittel innerhalb von 4°, sonst schwach.

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

Die besten Städte für ein Horoskop

POST /v1/locations/rank erwartet birth, optional focus (eine beliebige Auswahl aus identity, love, body, money, home, mind), optional region und limit von 3 bis 12 und erstellt eine Rangliste aus einem Katalog von 61 großen Städten. Nicht jede Stadt der Erde wird verglichen; jeden anderen Ort kann man mit dem Endpunkt oben bewerten.

{
  "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°"
      ]
    }
  ]
}

Limits und Preise

Anfragen werden pro Konto gezählt, über alle seine Schlüssel hinweg, und das Kontingent füllt sich um 00:00 UTC wieder auf. Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine als ungültig abgelehnte Anfrage wird nicht gezählt, eine Berechnung, die auf unserer Seite fehlschlägt, wird wieder gutgeschrieben, und GET /v1/usage ist immer kostenlos. API Pro ist ein eigenes Abo, getrennt von den App-Tarifen: Es enthält kein Premium für die App, und Premium für die App enthält es nicht. Auch die beiden Kontingente sind getrennt: Die App zählt KI-Antworten pro Woche, diese API zählt Berechnungen pro UTC-Tag, und keines verbraucht das andere.

Fehler

Jeder Fehler hat dieselbe Form: { "error": { "code", "message", "details"?, "docs" } }.

Berechnungseinstellungen

Sie sind fest vorgegeben, und es sind die Einstellungen der App selbst, ausführlich beschrieben auf der Seite Dein Horoskop prüfen und im Genauigkeitsbericht mit JPL Horizons der NASA abgeglichen. Datendateien der Swiss Ephemeris mit aktiviertem Geschwindigkeits-Flag. Tropischer Tierkreis, geozentrische, scheinbare Positionen. Placidus-Häuser. Wahrer Mondknoten. Lilith als oskulierendes Mondapogäum. Glückspunkt als ASC + Mond − Sonne, für Tag- und Nachthoroskope gleichermaßen. Nur die fünf Hauptaspekte: Konjunktion 8°, Sextil 6°, Quadrat 8°, Trigon 8°, Opposition 8°. Jeder Aspekt im Geburtshoroskop und jeder Transitaspekt gibt an, ob er applikativ oder separativ ist, bestimmt aus den Geschwindigkeiten beider Himmelskörper, Rückläufigkeit eingeschlossen.

Datenschutz

Geburtsdaten sind personenbezogene Daten. Die API liest sie, rechnet, antwortet und vergisst sie: Kein Anfrageinhalt wird gespeichert, und nichts, was du sendest, wird für etwas anderes als die Antwort verwendet. Pro Anfrage speichern wir den Endpunkt, den Statuscode und die Antwortzeit. Mehr dazu in der Datenschutzerklärung.

Fragen