AstroAPI

Appearance

Einbettbare Widgets ​

Erstellen und verwalten Sie einbettbare Widgets für Ihre Website. Ein Widget ist eine fertige UI-Komponente für genau eine Astrologie-Funktion: ein Formular für ein Geburtshoroskop, ein Mondkalender, eine Zeichenauswahl für das Tageshoroskop. Sie konfigurieren es im Dashboard oder über diese API und binden es mit einem einzigen Script-Tag auf jeder beliebigen Seite ein.

Zwei APIs, zwei Schlüssel

  • Die Verwaltungs-API (/api/widgets) erstellt und konfiguriert Widgets. Sie verwendet Ihren normalen API-Schlüssel.
  • Die Widget-API (/api/widget-api) ist das, was das SDK aus dem Browser des Besuchers aufruft. Sie verwendet den eigenen Schlüssel des Widgets, der gefahrlos in einer Seite stehen darf, weil er auf dieses eine Widget beschränkt ist.

Sie suchen die Anleitung ohne Code? Siehe Widgets zu Ihrer Website hinzufügen.

Widget-Typen ​

Welche Widget-Typen Sie erstellen können, hängt von den Modulen Ihrer Organisation ab. GET /api/widgets/options listet die für Sie verfügbaren Typen auf.

TypBeschreibungErforderliche Module
natalFormular für Geburtsdaten mit Horoskop, Positionen und Aspektenmodule:natal
synastryZwei Formulare für Geburtsdaten, Synastrie-Horoskop und wechselseitige Aspektemodule:natal, module:synastry
transitGeburtsdaten plus ein Transitzeitpunkt, Bi-Wheel-Horoskopmodule:natal, module:transits
compositeZwei Formulare für Geburtsdaten, Komposit-Horoskopmodule:natal, module:composite
moonphaseAktuelle Mondphase mit Beleuchtungsgradmodule:moon
daily-horoscopeZeichenauswahl mit dem Horoskop für heutemodule:daily-report
numerologyFormular für Name und Geburtsdatum mit den Kernzahlenmodule:numerology
compatibilityZwei Personen, numerologischer Kompatibilitätswertmodule:numerology, module:compatibility
moon-calendarMonatskalender mit Phasen, Mondaufgang und Monduntergangmodule:moon

Widget-Verwaltung ​

Alle Verwaltungs-Endpunkte sind JSON:API und verwenden den Ressourcentyp widget.

Widgets auflisten ​

bash
curl "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key"

Widget abrufen ​

bash
curl "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

Widget erstellen ​

bash
curl -X POST "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "attributes": {
        "name": "My Natal Chart Widget",
        "widgetType": "natal",
        "allowedDomains": ["example.com", "www.example.com"],
        "customization": {
          "language": "en",
          "layout": { "variant": "card" },
          "colors": {
            "primary": "#5b2d8e",
            "background": "#ffffff",
            "text": "#1a1a1a"
          },
          "widgetOptions": {
            "showAspects": true,
            "showPoints": true,
            "showHouses": true,
            "chartSize": "medium",
            "theme": "auto"
          }
        }
      }
    }
  }'

Die Antwort auf das Erstellen ist der einzige Moment, in dem der vollständige API-Schlüssel des Widgets zurückgegeben wird (apiKey). Speichern Sie ihn oder erzeugen Sie ihn später neu; jede andere Antwort enthält nur apiKeyPrefix.

json
{
    "data": {
        "type": "widget",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "customization": { "...": "as sent, merged with defaults when served" },
            "allowedDomains": ["example.com", "www.example.com"],
            "enabled": true,
            "createdAt": "2026-06-15T12:00:00.000Z",
            "updatedAt": "2026-06-15T12:00:00.000Z",
            "apiKey": "wk_live_...",
            "apiKeyPrefix": "wk_live_abc1"
        },
        "relationships": {
            "organization": { "data": { "type": "organization", "id": "org_..." } }
        }
    }
}

Widget aktualisieren ​

PATCH akzeptiert eine beliebige Teilmenge aus name, enabled, allowedDomains und customization. Die Customization wird als Ganzes ersetzt, senden Sie also das vollständige Objekt.

bash
curl -X PATCH "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "id": "wgt_abc123",
      "attributes": {
        "name": "Updated Widget Name",
        "customization": { "language": "nl" }
      }
    }
  }'

Widget löschen ​

bash
curl -X DELETE "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

Den API-Schlüssel des Widgets neu erzeugen ​

bash
curl -X POST "https://api.astroapi.cloud/api/widgets/wgt_abc123/regenerate-key" \
  -H "X-Api-Key: your-api-key"

Gibt das Widget mit einem frischen apiKey zurück. Aktualisieren Sie den Einbettungscode auf Ihrer Website mit dem neuen Schlüssel; die Widget-ID bleibt dieselbe.

Verfügbare Widget-Optionen ​

bash
curl "https://api.astroapi.cloud/api/widgets/options" \
  -H "X-Api-Key: your-api-key"
json
{
    "data": {
        "type": "widget-options",
        "id": "org_...",
        "attributes": {
            "plan": "Gold",
            "organizationModules": ["module:natal", "module:moon"],
            "availableWidgetTypes": ["natal", "moonphase", "moon-calendar"],
            "features": {
                "canRemoveBranding": false,
                "canUseCustomLogo": false,
                "canUseCustomCss": false,
                "maxDomains": 5
            },
            "allWidgetTypes": [
                {
                    "id": "natal",
                    "name": "Natal Chart",
                    "requiredModules": ["module:natal"],
                    "displayOptions": { "showChartSize": true, "showAspects": true, "showPoints": true }
                }
            ]
        }
    }
}

Tarif-Funktionen ​

FunktionBeschreibung
canRemoveBrandingbranding.showPoweredBy darf false sein
canUseCustomLogobranding.logoUrl und branding.companyName dürfen gesetzt werden
canUseCustomCsscustomCss wird an das Widget ausgeliefert
maxDomainsMaximale Anzahl an allowedDomains pro Widget, oder "unlimited"

Customization-Objekt ​

Jedes Feld ist optional; was Sie weglassen, wird bei der Auslieferung aus den unten stehenden Standardwerten ergänzt. Farben sind CSS-Farbwerte, Größen sind Zahlen in Pixeln.

json
{
    "colors": {
        "primary": "#6366f1",
        "secondary": "#8b5cf6",
        "background": "#ffffff",
        "surface": "#f8fafc",
        "text": "#1e293b",
        "textSecondary": "#64748b",
        "border": "#e2e8f0",
        "error": "#ef4444",
        "success": "#22c55e",
        "accent": "#f59e0b"
    },
    "fonts": {
        "family": "Inter, system-ui, sans-serif",
        "sizeBase": 16,
        "sizeHeading": 24,
        "sizeSmall": 12,
        "weightNormal": 400,
        "weightBold": 600
    },
    "borders": { "radius": 8, "width": 1, "style": "solid" },
    "spacing": { "padding": 16, "margin": 16 },
    "shadows": { "preset": "sm", "custom": null },
    "layout": { "variant": "card" },
    "interaction": {
        "tooltipEnabled": true,
        "animationsEnabled": true,
        "clickThroughEnabled": false,
        "clickThroughUrl": null
    },
    "chartSettings": {},
    "labels": {},
    "language": "en",
    "branding": { "showPoweredBy": true, "logoUrl": null, "companyName": null },
    "customCss": null,
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": "medium",
        "theme": "light"
    },
    "numerologyOptions": {
        "showLifePath": true,
        "showExpression": true,
        "showSoulUrge": true,
        "showPersonality": true,
        "showBirthday": true,
        "showPersonalCycles": true
    },
    "dailyHoroscopeOptions": { "autoRefresh": false },
    "moonCalendarOptions": {
        "showMoonrise": true,
        "showMoonset": true,
        "showIllumination": true,
        "showPhaseEmoji": true,
        "highlightFullMoon": true,
        "highlightNewMoon": true
    },
    "compatibilityOptions": {
        "showScore": true,
        "showDescription": true,
        "showLifePaths": true
    }
}

Customization-Felder ​

FeldTypBeschreibung
colors.*stringZehn CSS-Farben, die als CSS-Variablen auf das Widget angewendet werden
fonts.familystringWert für CSS-font-family
fonts.sizeBase / sizeHeading / sizeSmallnumberSchriftgrößen in Pixeln
fonts.weightNormal / weightBoldnumberSchriftstärken
borders.radius / widthnumberPixel; verwendet von Eingabefeldern, Schaltflächen und dem Karten-Layout
borders.stylestringsolid, dashed, dotted oder none
spacing.padding / marginnumberPixel; die Layouts card und compact verwenden padding
shadows.presetstringnone, sm, md, lg oder xl (Karten-Layout)
shadows.customstring | nullEin CSS-box-shadow, der das Preset überschreibt
layout.variantstringSiehe Layout-Varianten
interaction.tooltipEnabledbooleanTooltips beim Überfahren von Planetenzeilen, Aspektzeilen und Kalendertagen
interaction.animationsEnabledbooleanEinblendanimationen; immer aus für Besucher, die reduzierte Bewegung bevorzugen
interaction.clickThroughEnabledbooleanMacht das gezeichnete Horoskop zu einem Link auf clickThroughUrl
interaction.clickThroughUrlstring | nullÖffnet in einem neuen Tab
chartSettingsobjectEin partielles Horoskop-Theme, das über das Standard-Theme gelegt wird: Farben pro Zeichen, Punkt und Aspekt, Linienstärken, showDegrees, showRetrograde und so weiter
labelsobjectÜberschreibungen für jeden Label-Schlüssel; siehe Sprachen und Labels
languagestringEiner der 13 unterstützten Sprachcodes
branding.showPoweredBybooleanErfordert canRemoveBranding, um auf false gesetzt zu werden
branding.logoUrl / companyNamestring | nullErfordern canUseCustomLogo
customCssstring | nullWird für das Widget in die Seite injiziert; erfordert canUseCustomCss
widgetOptions.showAspects / showPointsbooleanZeigt die Aspekt- und Positionstabellen unter einem Horoskop
widgetOptions.showHousesbooleanZeigt Häusernummern im Horoskop
widgetOptions.chartSizestring | numbersmall (300), medium (450), large (600) oder eine Breite in Pixeln
widgetOptions.themestringlight, dark, cosmic, custom oder auto
numerologyOptions.*booleanWelche Zahlen das Numerologie-Widget anzeigt
dailyHoroscopeOptions.autoRefreshbooleanReserviert
moonCalendarOptions.*booleanWelche Details ein Kalendertag zeigt und welche Phasen hervorgehoben werden
compatibilityOptions.*booleanScore-Ring, Beschreibung und Lebenszahlen

Layout-Varianten ​

WertBeschreibung
cardUmrandete Fläche mit dem konfigurierten Radius, Padding und Schatten (Standard)
compactHalbes Padding und etwas kleinere Schrift, für Seitenleisten
fullVon Rand zu Rand, nur vertikales Padding
minimalÜberhaupt kein Rahmen; übernimmt alles von der Seite

Themes ​

light, dark und cosmic sind feste Paletten für Flächen und Rahmen. auto verwendet die helle Palette und wechselt zur dunklen, sobald das System des Besuchers Dunkel bevorzugt. custom setzt nichts und verlässt sich auf Ihre colors. In jedem Theme haben die zehn colors, die Sie setzen, Vorrang vor der Palette.

Sprachen und Labels ​

Das SDK liefert Labels für en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja und zh-CN. Regionsvarianten fallen für alles, was sie nicht selbst überschreiben, auf ihre Basissprache zurück. labels überschreibt einzelne Texte zusätzlich zur gewählten Sprache, zum Beispiel:

json
{ "language": "nl", "labels": { "calculateButton": "Bereken mijn horoscoop" } }

Die Sprache lässt sich auch pro Seite setzen: data-lang="de" am Script-Tag oder ?lang=de in der Seiten-URL, beide haben Vorrang vor der gespeicherten Sprache.

Ein Widget einbetten ​

Das SDK wird von https://widgets.astroapi.cloud/sdk.js ausgeliefert. Der Tab Embed im Dashboard erzeugt beide Snippets unten mit Ihren eigenen IDs.

Automatisch initialisieren ​

html
<script
  src="https://widgets.astroapi.cloud/sdk.js"
  data-widget-id="wgt_abc123"
  data-api-key="your-widget-api-key"
  data-api-url="https://api.astroapi.cloud"
></script>
<div id="astro-widget-wgt_abc123"></div>

Optionale Attribute: data-container="#my-element", um an anderer Stelle als im standardmäßigen div zu rendern, und data-lang="nl", um die Sprache zu überschreiben.

Programmatisch ​

html
<script src="https://widgets.astroapi.cloud/sdk.js"></script>
<div id="my-widget"></div>
<script>
  AstroWidget.create({
    widgetId: "wgt_abc123",
    apiKey: "your-widget-api-key",
    apiBaseUrl: "https://api.astroapi.cloud",
    container: "#my-widget",
    language: "nl",
    defaultValues: {
      dateTime: "1990-06-15T14:30:00",
      latitude: 52.3676,
      longitude: 4.9041,
      timezone: "Europe/Amsterdam",
      placeName: "Amsterdam"
    },
    onLoad: () => console.log("Widget loaded"),
    onResult: (result) => console.log("Result", result),
    onError: (err) => console.error(err)
  }).then((widget) => {
    // widget.type, widget.getResult(), widget.setBirthData(), widget.calculate(), widget.destroy()
  });
</script>

defaultValues.dateTime wird als Ortszeit in timezone interpretiert; das Formular zeigt den Wert genau so an, wie Sie ihn angeben.

Instanz-API ​

ElementBeschreibung
id, typeWidget-ID und Widget-Typ
getResult()Das letzte Ergebnis, gleich ob der Besucher es berechnet hat oder calculate()
setBirthData(data)Geburtsdaten, die calculate() verwendet
calculate()Führt die Berechnung per Script aus und zeigt das Ergebnis an. Unterstützt für natal, transit (zum aktuellen Zeitpunkt), moonphase und moon-calendar (aktueller Monat); die übrigen Typen beziehen ihre Eingabe vom Besucher und liefern einen Fehler zurück
destroy()Entfernt das Widget aus der Seite

onResult wird bei jedem Ergebnis ausgelöst, das das Widget anzeigt, und zwar für alle Widget-Typen. AstroWidget.version gibt den Build des SDK aus.

Domains ​

allowedDomains schränkt ein, wo der API-Schlüssel des Widgets funktioniert, geprüft gegen die Origin der Browser-Anfrage. Subdomain-Wildcards (*.example.com) werden unterstützt, und www. wird wie die nackte Domain behandelt. Bei einer leeren Liste funktioniert der Schlüssel auf jeder Domain, füllen Sie sie also aus, bevor Sie den Einbettungscode veröffentlichen.

Widget-API ​

Dies sind die Endpunkte, die das SDK stellvertretend für einen Besucher aufruft. Sie sind hier aufgeführt, damit Sie ein eigenes Frontend gegen ein Widget bauen können; das SDK ist der Referenz-Client.

Die Authentifizierung erfolgt über den API-Schlüssel des Widgets in X-Api-Key. Die Vorschau im Dashboard verwendet stattdessen eine Session.

EndpunktBodyWidget-Typ
GET /api/widget-api/config/:widgetId—beliebig; öffentlich, gibt widgetType und die zusammengeführte customization zurück
POST /api/widget-api/natal/:widgetId{ birthData }natal
POST /api/widget-api/synastry/:widgetId{ person1, person2 }synastry
POST /api/widget-api/transit/:widgetId{ birthData, transitDateTime, transitTimezone? }transit
POST /api/widget-api/composite/:widgetId{ person1, person2 }composite
POST /api/widget-api/moonphase/:widgetId{ date?, latitude? }moonphase
POST /api/widget-api/daily-horoscope/:widgetId{ zodiacSign, date? }daily-horoscope
POST /api/widget-api/numerology/:widgetId{ fullName, birthYear, birthMonth, birthDay }numerology
POST /api/widget-api/compatibility/:widgetId{ person1, person2 } (Name und Bestandteile des Geburtsdatums)compatibility
POST /api/widget-api/moon-calendar/:widgetId{ year, month, latitude?, longitude?, timezone? }moon-calendar
GET /api/widget-api/geocoding/search/:widgetId?q=&limit=&lang=—beliebig; Ortssuche für das Formular mit Geburtsdaten

birthData, person1 und person2 sind bei den Horoskop-Widgets { dateTime, latitude, longitude, timezone, placeName? }, wobei dateTime die Ortszeit (1990-06-15T14:30:00) in timezone ist. Der Aufruf eines Endpunkts für ein Widget eines anderen Typs liefert 400; ein deaktiviertes Widget liefert 403; eine Anfrage von einer Domain außerhalb von allowedDomains liefert 403 DOMAIN_NOT_ALLOWED.

Nächste Schritte ​

AstroAPI Documentation

Copyright © 2026 AstroAPI