Feldformate

• URL – Basis https://api.occultapi.com, dann die Route genau wie angegeben, mit Schrägstrich am Ende.
  Richtig: /api/astro/tithi/, /api/astro/dasha/vimshottari/, /api/festivals/.
  Falsch: /api/astro/tithi, /astro/tithi/, /api/astro/Tithi/.
• Authentifizierung – dein Schlüssel im Header X-API-Key und bei jedem POST Content-Type: application/json.
• Methode – POST mit JSON-Body. Die wenigen GET-Abfragen (Ortssuche, Ayanamsa-Wert, die Shalaka-Tafeln und die Daten zu Naturereignissen) erwarten ihre Eingaben, falls es welche gibt, als Query-Parameter.
  Richtig: POST /api/astro/panchanga/ mit JSON-Body; GET /api/astro/geocode/?address=Jaipur.

• date_time – ISO 8601 mit UTC-Offset oder abschließendem Z, für den zu berechnenden Zeitpunkt (beim Geburtshoroskop also der Geburtszeitpunkt).
  Richtig: "1990-08-15T10:30:00+05:30", "2026-09-01T00:30:00Z".
  Falsch: "1990-08-15 10:30:00" (ohne Offset: Die meisten Endpoints lesen das als UTC+05:30, einige als UTC), "15/08/1990 10:30 AM".
• datetime – derselbe Wert unter anderem Namen. /api/astro/chart/, die Routen der Teilhoroskope und /api/astro/planet-positions/ verlangen genau diese Schreibweise; die Dasha-Routen akzeptieren beide.
• date und time – nur bei /api/astro/date_time/. Der Endpoint nimmt die lokale Uhrzeit und die Koordinaten entgegen und liefert einen Zeitstempel mit dem Offset, der an diesem Datum galt.
  Richtig: "1990-08-15" und "10:30:00".
• year, month, day – einfache Ganzzahlen, wo ein Endpoint sie verlangt (Numerologie, Kalender, Jahres-Suchläufe).
  Richtig: 1990, 8, 15.

• latitude / longitude – in Dezimalgrad. Nord und Ost sind positiv, Süd und West negativ.
  Richtig: 26.9124, 75.7873 (Jaipur); 40.7128, -74.006 (New York).
  Falsch: "26°54′N", Strings oder 74.006 für New York (ohne Minus landet die Stadt in China).
• timezone_as_float – der UTC-Offset in Stunden als Zahl von -12 bis 14, und zwar der, der an diesem Ort an diesem Datum galt (inklusive Sommerzeit).
  Richtig: 5.5 (Indien), -4 (New York im Sommer), 5.75 (Nepal).
  Falsch: "+05:30", "Asia/Kolkata", "IST".
• Bei manchen Endpoints heißt derselbe Offset anders: timezone (zum Beispiel bei /api/astro/dosha/ und /api/astro/strength/), tz (/api/astro/transit/) und time_zone (/api/astro/celestial/). Schick immer den Namen, den der Endpoint angibt.

• ayanamsa (siderische Endpoints) – ein Ayanamsa-Name, Groß- und Kleinschreibung egal; Standard ist LAHIRI. /api/astro/chart/ verlangt das Feld.
  Richtig: LAHIRI, KRISHNAMURTI, RAMAN, TRUE_CITRA.
  Falsch: "kp-newcomb", "Lahiri ayanamsa". Bei /api/astro/chart/ führt ein unbekannter Name zu 400.
• Bei den Routen /api/astro/western/ und /api/astro/return/ ist ayanamsa standardmäßig TROPICAL. Gib einen Ayanamsa-Namen an, wenn du stattdessen siderische Positionen willst.
• Endpoints ohne Feld ayanamsa rechnen mit Lahiri. /api/astro/prashna/jamakkol/ hat eine eigene Liste in Kleinbuchstaben: lahiri, true_citra, krishnamurti, raman.

• keys – ein JSON-Array mit den exakten Namen aus der Key-Tabelle des Endpoints.
  Richtig: ["tithi", "vaara", "rahu_kaalam"] bei /api/astro/panchanga/.
  Falsch: "tithi,vaara" (ein String), "Tithi", "rahu_kaal".
• Manche Keys brauchen ein zusätzliches Feld, das in der Key-Tabelle steht: Der Key phone_number bei /api/astro/numerology/ braucht einen Wert für phone_number.
• Hat die Referenz eines Endpoints keine Key-Tabelle, etwa bei /api/astro/tithi/ oder /api/astro/rahu-kaal/, führt er immer dieselbe Berechnung aus. keys musst du dann nicht mitschicken.

• chart_name bei /api/astro/chart/ – PascalCase, Groß- und Kleinschreibung zählt. Schick ein Array, um mehrere Horoskope in einem Aufruf zu bekommen.
  Richtig: "RashiChart", ["RashiChart", "NavamsaChart", "DasamsaChart"].
  Falsch: "rashi", "D9", "Navamsa".
• notation – kleingeschrieben degree (Dezimalgrad) oder astrological (Zeichen, Grad, Minuten, Sekunden).
• Mondknoten – rahu bei den Horoskop-Routen (Standard true, alternativ mean oder both), node bei den Dasha- und Jaimini-Routen (Standard true, alternativ mean), node_type bei Human Design und Prashna (Standard mean, außer bei /api/astro/prashna/, wo das Feld Pflicht ist).
• house_system bei /api/astro/western/house-cusps/ – kleingeschrieben, Wörter mit Unterstrich getrennt.
  Richtig: placidus (Standard), whole_sign, equal, koch, porphyry, regiomontanus, campanus, topocentric.
  Falsch: "whole-sign", "W".
• rashi bei den Rashifal-Routen – englische Namen der Tierkreiszeichen.
  Richtig: aries, taurus, … pisces.
• system bei /api/astro/numerology/ – chaldean (Standard), pythagorean, chinese oder vedic. Jedes System hat eigene Keys.
• spread bei /api/astro/tarot/spread/ – three_card (Standard), one_card, celtic_cross, horseshoe, relationship oder situation.
• sequence bei /api/astro/numerology/angel/ – die gesehene Zahl als String.
  Richtig: "1111", "444".
  Falsch: 1111 (eine Zahl).
• levels bei den Dasha-Zeitleisten – 1 bis 4, Standard 3: 1 liefert nur Mahadashas, 2 zusätzlich Antardashas, 3 auch Pratyantardashas.

Jede Route endet mit einem Schrägstrich. Fehlt er, antwortet der Server mit 301 und leitet auf die URL mit Schrägstrich um. Die meisten HTTP-Clients folgen dieser Umleitung als GET ohne deinen Body – und der Aufruf scheitert. Übernimm die Schreibweise der Route exakt: Manche nutzen Bindestriche (/api/astro/rahu-kaal/), manche Unterstriche (/api/astro/monthly_panchang/), und einige liegen außerhalb von /api/astro/ (/api/festivals/, /api/vrat-upavas/).

• /docs/agent-gotchas — Fachliche Fallstricke
• /docs/agent-tasks — Agenten-Spickzettel: Aufgaben