Entwickler

Geburtshoroskop-API

Astrologische Berechnungen als JSON, ausgeführt mit der Swiss Ephemeris: derselbe Rechenkern, der jedes Horoskop in NatalChart.AI zeichnet, ohne die Deutungsebene. Keine KI-Aufrufe, deshalb liefert dieselbe Eingabe immer dieselben Zahlen.

✦ Swiss Ephemeris✦ 10 Anfragen pro Tag kostenlos✦ Anfrageinhalte werden nie gespeichert

Aktualisiert am · Nächste Prüfung am

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 im Tab API & MCP der App-Einstellungen.

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

Codebeispiele

Dieselbe Anfrage in JavaScript, Python und PHP. Jeder HTTP-Client funktioniert, und das OpenAPI-Dokument lässt einen Codegenerator den Client für dich schreiben.

JavaScript

const res = await fetch("https://api.natalchart.ai/v1/chart/short", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NATALCHART_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ birth: { date: "1991-09-06", time: "18:30", latitude: 50.4501, longitude: 30.5234 } }),
});
const chart = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.natalchart.ai/v1/chart/short",
    headers={"Authorization": f"Bearer {os.environ['NATALCHART_API_KEY']}"},
    json={"birth": {"date": "1991-09-06", "time": "18:30", "latitude": 50.4501, "longitude": 30.5234}},
)
chart = res.json()

PHP

$ch = curl_init("https://api.natalchart.ai/v1/chart/short");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("NATALCHART_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["birth" => ["date" => "1991-09-06", "time" => "18:30", "latitude" => 50.4501, "longitude" => 30.5234]]),
]);
$chart = json_decode(curl_exec($ch), true);

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"
  }
}
FeldErforderlichBedeutung
datejaGeburtsdatum, YYYY-MM-DD, von 1800 bis 2399.
timeneinOrtszeit, HH:mm, 24-Stunden-Format. null, wenn unbekannt.
latitude, longitudejaDezimalgrad, Nord und Ost positiv.
timezoneneinIANA-Zeitzone. Fehlt sie, wird sie aus den Koordinaten ermittelt, mit den Sommerzeitregeln dieses Datums.

Endpunkte

EndpunktTarifLiefert
POST /v1/chart/shortFreeDas kurze Horoskop: Sonne, Mond und Aszendent mit Graden, das Zeichen jedes Himmelskörpers, die rückläufigen Himmelskörper, das dominierende Element und die dominierende Qualität.
POST /v1/chart/fullFreeDas vollständige Horoskop: jeder Himmelskörper mit Länge, Zeichen, Grad, Geschwindigkeit, Rückläufigkeits-Flag und Haus; die Achsen; zwölf Häuserspitzen nach Placidus; die Aspekte mit Orben; die Gewichtung nach Elementen und Qualitäten; Fixsternkontakte.
POST /v1/chart/planetsFreeNur die Himmelskörper: Länge, Zeichen, Grad im Zeichen, Tagesbewegung, Rückläufigkeits-Flag, Haus.
POST /v1/chart/anglesFreeAszendent, Medium Coeli, Vertex und Glückspunkt.
POST /v1/chart/housesFreeDie zwölf Häuserspitzen nach Placidus.
POST /v1/chart/aspectsFreeDie fünf Hauptaspekte zwischen den Himmelskörpern, jeweils mit Winkel und Orbis, und die verwendete Orbentabelle.
POST /v1/chart/elementsFreeDie Gewichtung nach Elementen und Qualitäten, mit dem dominierenden Element und der dominierenden Qualität.
POST /v1/chart/fixed-starsFreeKonjunktionen von Fixsternen mit den Himmelskörpern des Geburtshoroskops innerhalb von 1,5 Grad.
POST /v1/horoscope/dailyFreeDer berechnete Tag: der Himmel um 12:00 Uhr UTC, die Mondphase, die Himmelsereignisse der kommenden Woche und, mit Geburtsdaten, jeder Transit zum Geburtshoroskop mit seinem Orbis. Kein generierter Text.
GET /v1/skyFreePlanetenpositionen, Mondphase und die Himmelsereignisse der kommenden Woche für ein Datum (?date=YYYY-MM-DD, standardmäßig heute). Funktioniert ohne Schlüssel.
GET /v1/usageFreeDein Tarif, der heutige Zählerstand und wann sich das Kontingent wieder auffüllt. Kostet nichts.
POST /v1/transitsPremium und MAXBis zu 60 Transitereignisse in einem Zeitraum von bis zu 92 Tagen, bei mehr Ereignissen die bedeutendsten: exakte Transitaspekte zum Geburtshoroskop nach Datum, Zeichenwechsel und Stillstände.
POST /v1/synastryPremium und MAXZwei Horoskope im Vergleich: Aspekte zwischen den Horoskopen mit Orben, Hausüberlagerungen in beide Richtungen und ein Wert je Lebensbereich.
POST /v1/solar-returnPremium und MAXDas Solarhoroskop für ein Jahr, berechnet für den Geburtsort oder einen anderen Ort.
POST /v1/timingPremium und MAXJeder Tag eines Zeitraums von bis zu 62 Tagen, bewertet für eine Aktivität (general, business, romance, health, creative, travel, home, clarity): fördernde und hemmende Transite, Phase und Zeichen des Mondes, Mond im Leerlauf. Die fünf besten Tage zuerst.
POST /v1/locations/scorePremium und MAXEin Ort, gemessen an einem Horoskop: die umgerechneten Achsen, die Planeten darauf mit Orben, ein Wert für jeden Lebensbereich und ein Gesamtwert.
POST /v1/locations/rankPremium und MAXDer Katalog großer Städte als Rangliste für ein Horoskop, insgesamt oder nach ausgewählten Lebensbereichen, weltweit oder in einer Region.

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 Premium und MAX

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 bis zu 60 Ereignisse im Zeitraum, bei mehr Ereignissen die bedeutendsten: exakte Transitaspekte zum Geburtshoroskop nach Datum, Zeichenwechsel und Stillstände, in zeitlicher Reihenfolge. Außerdem nennt er 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",
      "at": "2026-09-19T10:10:33.151Z",
      "date": "2026-09-19",
      "position": "14°06′ Libra",
      "house": 8,
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "targetPosition": "14°06′ Capricorn",
      "targetHouse": 11,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "at": "2026-09-22T09:53:49.800Z",
      "date": "2026-09-22",
      "position": "18°00′ Leo",
      "house": 7,
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "targetPosition": "18°00′ Scorpio",
      "targetHouse": 8,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "at": "2026-09-23T20:47:58.234Z",
      "date": "2026-09-23",
      "position": "0°51′ Libra",
      "house": 7,
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "targetPosition": "0°51′ Aquarius",
      "targetHouse": 12,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "at": "2026-09-26T12:58:36.996Z",
      "date": "2026-09-26",
      "position": "3°28′ Libra",
      "house": 7,
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "targetPosition": "3°28′ Libra",
      "targetHouse": 7,
      "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

TarifPreisAnfragenEndpunkte
Free$010 pro TagHoroskope, Segmente, Tageshoroskop, Himmel
Premium$9.99 pro Monat oder $79 pro Jahr100 pro TagAlles: Transite, Synastrie, Solarhoroskope, beste Tage, Orte
MAX$19.99 pro Monat oder $179 pro JahrKein TageslimitAlles: Transite, Synastrie, Solarhoroskope, beste Tage, Orte

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. Premium und MAX sind die Tarife der App selbst: Ein Abo umfasst die App, die API und den MCP-Server und wird wie jeder App-Tarif gekündigt, über Abo verwalten. Die Kontingente bleiben 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", "upgrade_url"? } }.

StatusCodeWann
400invalid_requestDer Anfrageinhalt ist ungültig. details listet jedes Problem auf. Wird nicht gezählt.
401missing_api_key, invalid_api_keyKein Schlüssel, ein unbekannter oder ein widerrufener Schlüssel.
403plan_requiredEin Endpunkt für Premium oder MAX, im Free-Tarif aufgerufen.
429daily_limit_reachedDas Tageskontingent ist aufgebraucht. Es füllt sich um 00:00 UTC wieder auf.
500internal_errorEin Fehler auf unserer Seite. Die Anfrage wird nicht gezählt.

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 an einem veröffentlichten Testhoroskop mit JPL Horizons der NASA verglichen. 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.

Im Produktivbetrieb

In den letzten 30 Tagen (vom 19. September 2026 bis zum 16. Oktober 2026) beantwortete der Server eine Berechnung im Median in 280 ms und im 95. Perzentil in 526 ms, gemessen vom Eingang der Anfrage bis zum Versand der Antwort. Der Genauigkeitsbericht vergleicht die Zahlen für ein veröffentlichtes Testhoroskop mit NASA JPL Horizons.

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.

Änderungsprotokoll

  • 2. November 2026: Die API und der MCP-Server gehören jetzt zu den Tarifen der App NatalChart.AI: alle Endpunkte mit Premium bei 100 Anfragen pro Tag und mit MAX ohne Tageslimit. Die Schlüssel ziehen in die App um, in den Tab API & MCP der Einstellungen.
  • 16. Oktober 2026: Die Antworten 429 und 403 nennen den Preis und enthalten ein Feld upgrade_url mit dem Link zum Upgrade.
  • 3. Oktober 2026: Die Ortswerte nutzen dasselbe Modell wie die App NatalChart.AI, und /v1/locations/score ergänzt overall10.
  • 2. Oktober 2026: Der MCP-Server startet unter https://www.natalchart.ai/mcp und ist in der offiziellen MCP Registry gelistet.
  • 22. September 2026: Schlüssel werden ohne Präfix, in Anführungszeichen oder mit doppeltem Bearer angenommen, und jede Antwort mit 401 sagt, was schiefgelaufen ist.
  • 19. September 2026: Beste Tage und die beiden Orts-Endpunkte kommen zur API hinzu, damit sind es insgesamt siebzehn Endpunkte.
  • 18. September 2026: Die API startet (Geburtshoroskope, Tageshoroskop und Himmel mit einem kostenlosen Schlüssel; Transite, Synastrie und Solarhoroskope mit einem bezahlten Tarif).

Fragen

Nutzt die API KI?

Nein. Jeder Endpunkt ist eine Berechnung: Planetenpositionen aus der Swiss Ephemeris, Häuserspitzen, Aspekte, Transite. Es wird kein Text generiert und kein Sprachmodell aufgerufen, deshalb liefert dieselbe Eingabe immer dieselben Zahlen.

Kann ich das Häusersystem oder einen siderischen Tierkreis wählen?

Nein. Jedes Horoskop ist tropisch mit Placidus-Häusern, mit denselben Einstellungen, die die App NatalChart.AI verwendet. Wenn du Whole Sign (jedes Zeichen ein ganzes Haus), Koch oder einen siderischen Tierkreis brauchst, ist das nicht die richtige API dafür.

Was passiert, wenn die Geburtszeit unbekannt ist?

Sende time als null. Die Positionen werden für angenommene 12:00 Uhr Ortszeit berechnet, was die Antwort als assumedLocalTime angibt, und was die genaue Uhrzeit braucht, wird zurückgehalten statt geraten: Die Achsen (Aszendent, Medium Coeli, Vertex, Glückspunkt) und die Häuserspitzen kommen als null zurück, und die Himmelskörper haben kein Haus. Eine Warnung sagt, dass der Mond um bis zu etwa 7,5 Grad abweichen und im Nachbarzeichen stehen kann; auch ein Himmelskörper oder Aspekt nahe einer Zeichen- oder Orbisgrenze kann zur tatsächlichen Uhrzeit anders ausfallen.

Werden Ortsnamen geokodiert?

Nein. Sende Breiten- und Längengrad. Die Zeitzone wird aus den Koordinaten ermittelt, mit den historischen Sommerzeitregeln für dieses Datum, es sei denn, du übergibst selbst eine IANA-Zeitzone.

Werden die Geburtsdaten gespeichert, die ich sende?

Nein. Anfrageinhalte werden nirgends abgelegt. Das Anfrageprotokoll enthält den Endpunkt, den Statuscode und die Antwortzeit, also das, was der Nutzungszähler braucht.

Was zählt als Anfrage?

Ein erfolgreicher Aufruf eines Berechnungsendpunkts. Eine als ungültig abgelehnte Anfrage kostet nichts, ein Fehler auf unserer Seite wird wieder gutgeschrieben, und /v1/usage ist kostenlos. Das Kontingent gilt pro Konto, nicht pro Schlüssel, und füllt sich um 00:00 UTC wieder auf: 10 pro Tag mit Free, 100 pro Tag mit Premium, kein Tageslimit mit MAX.

Kann ich sie in einem kommerziellen Produkt verwenden?

Ja, mit jedem Tarif. Bewahre deinen Schlüssel auf einem Server auf: Einen Schlüssel im Browser- oder App-Code kann jeder kopieren, der diesen Code öffnet.

Bereit für dein echtes Horoskop?

Mein kostenloses Horoskop erstellen