AstroAPI

Appearance

Widget Incorporabili ​

Crea e gestisci widget incorporabili per il tuo sito web. Un widget è un componente UI pronto all'uso per una singola funzionalità astrologica: un modulo per il tema natale, un calendario lunare, un selettore dell'oroscopo giornaliero. Lo configuri dalla dashboard o tramite questa API e lo inserisci in qualsiasi pagina con un solo tag script.

Due API, due chiavi

  • L'API di gestione (/api/widgets) crea e configura i widget. Usa la tua chiave API normale.
  • L'API del widget (/api/widget-api) è quella che il SDK chiama dal browser del visitatore. Usa la chiave propria del widget, che si può inserire in una pagina senza rischi perché è limitata a quel singolo widget.

Cerchi la guida senza codice? Vedi Aggiungere Widget al Tuo Sito Web.

Tipi di Widget ​

I tipi di widget che puoi creare dipendono dai moduli attivi sulla tua organizzazione. GET /api/widgets/options elenca quelli disponibili per te.

TipoDescrizioneModuli richiesti
natalModulo dei dati di nascita con tema, posizioni e aspettimodule:natal
synastryDue moduli dei dati di nascita, tema di sinastria e aspetti incrociatimodule:natal, module:synastry
transitDati di nascita più un momento di transito, tema a doppia ruotamodule:natal, module:transits
compositeDue moduli dei dati di nascita, tema compositomodule:natal, module:composite
moonphaseFase lunare attuale con l'illuminazionemodule:moon
daily-horoscopeSelettore del segno con l'oroscopo di oggimodule:daily-report
numerologyModulo con nome e data di nascita e i numeri principalimodule:numerology
compatibilityDue persone, punteggio di compatibilità numerologicamodule:numerology, module:compatibility
moon-calendarCalendario mensile con fasi, sorgere e tramontare della Lunamodule:moon

Gestione dei Widget ​

Tutti gli endpoint di gestione sono JSON:API e usano il tipo di risorsa widget.

Elenca i Widget ​

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

Ottieni un Widget ​

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

Crea un Widget ​

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

La risposta alla creazione è l'unica occasione in cui viene restituita la chiave API completa del widget (apiKey). Conservala, oppure rigenerala in seguito; tutte le altre risposte contengono solo 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_..." } }
        }
    }
}

Aggiorna un Widget ​

PATCH accetta qualsiasi sottoinsieme di name, enabled, allowedDomains e customization. La personalizzazione viene sostituita per intero, quindi invia l'oggetto completo.

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

Elimina un Widget ​

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

Rigenera la chiave API del widget ​

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

Restituisce il widget con una nuova apiKey. Aggiorna il codice di incorporamento sul tuo sito con la nuova chiave; l'ID del widget resta lo stesso.

Opzioni Widget Disponibili ​

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

Funzionalità del Piano ​

FunzionalitàDescrizione
canRemoveBrandingbranding.showPoweredBy può essere impostato a false
canUseCustomLogobranding.logoUrl e branding.companyName possono essere impostati
canUseCustomCsscustomCss viene servito al widget
maxDomainsNumero massimo di allowedDomains per widget, oppure "unlimited"

Oggetto di Personalizzazione ​

Ogni campo è facoltativo; ciò che ometti viene completato con i valori predefiniti qui sotto quando il widget viene servito. I colori sono stringhe di colore CSS, le dimensioni sono numeri in pixel.

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

Campi di Personalizzazione ​

CampoTipoDescrizione
colors.*stringDieci colori CSS, applicati come variabili CSS sul widget
fonts.familystringValore CSS font-family
fonts.sizeBase / sizeHeading / sizeSmallnumberDimensioni dei caratteri in pixel
fonts.weightNormal / weightBoldnumberSpessori dei caratteri
borders.radius / widthnumberPixel; usati dai campi di input, dai pulsanti e dal layout a scheda
borders.stylestringsolid, dashed, dotted o none
spacing.padding / marginnumberPixel; i layout card e compact usano padding
shadows.presetstringnone, sm, md, lg o xl (layout a scheda)
shadows.customstring | nullUn box-shadow CSS che sovrascrive il preset
layout.variantstringVedi Varianti di layout
interaction.tooltipEnabledbooleanTooltip al passaggio del mouse su righe dei pianeti, righe degli aspetti e giorni del calendario
interaction.animationsEnabledbooleanAnimazioni di ingresso; sempre disattivate per i visitatori che preferiscono meno movimento
interaction.clickThroughEnabledbooleanRende il tema renderizzato un link verso clickThroughUrl
interaction.clickThroughUrlstring | nullSi apre in una nuova scheda
chartSettingsobjectUn tema grafico parziale unito al tema predefinito: colori per segno, punto e aspetto, spessori delle linee, showDegrees, showRetrograde e così via
labelsobjectSostituzioni per qualsiasi chiave di etichetta; vedi Lingue ed etichette
languagestringUno dei 13 codici lingua supportati
branding.showPoweredBybooleanRichiede canRemoveBranding per impostarlo a false
branding.logoUrl / companyNamestring | nullRichiedono canUseCustomLogo
customCssstring | nullIniettato nella pagina per il widget; richiede canUseCustomCss
widgetOptions.showAspects / showPointsbooleanMostra le tabelle degli aspetti e delle posizioni sotto un tema
widgetOptions.showHousesbooleanMostra i numeri delle case sul tema
widgetOptions.chartSizestring | numbersmall (300), medium (450), large (600) oppure una larghezza in pixel
widgetOptions.themestringlight, dark, cosmic, custom o auto
numerologyOptions.*booleanQuali numeri mostra il widget di numerologia
dailyHoroscopeOptions.autoRefreshbooleanRiservato
moonCalendarOptions.*booleanQuali dettagli mostra un giorno del calendario e quali fasi vengono evidenziate
compatibilityOptions.*booleanAnello del punteggio, descrizione e numeri del sentiero di vita

Varianti di layout ​

ValoreDescrizione
cardSuperficie con bordo e con raggio, padding e ombra configurati (predefinito)
compactMetà del padding e caratteri leggermente più piccoli, per le barre laterali
fullDa bordo a bordo, solo padding verticale
minimalNessuna cornice; eredita tutto dalla pagina

Temi ​

light, dark e cosmic sono palette fisse per superfici e bordi. auto usa la palette chiara e passa a quella scura quando il sistema del visitatore preferisce il tema scuro. custom non imposta nulla e si affida ai tuoi colors. In ogni tema i dieci colors che imposti hanno la precedenza sulla palette.

Lingue ed etichette ​

Il SDK include le etichette per en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja e zh-CN. Le varianti regionali ricadono sulla lingua di base per tutto ciò che non sovrascrivono. labels sostituisce singole stringhe sopra la lingua scelta, ad esempio:

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

La lingua può anche essere impostata per pagina: data-lang="de" sul tag script, oppure ?lang=de nell'URL della pagina; entrambi hanno la precedenza sulla lingua memorizzata.

Incorporare un Widget ​

Il SDK viene servito da https://widgets.astroapi.cloud/sdk.js. La scheda Embed della dashboard genera entrambi gli snippet qui sotto con i tuoi ID già compilati.

Inizializzazione automatica ​

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>

Attributi facoltativi: data-container="#my-element" per il rendering in un elemento diverso dal div predefinito e data-lang="nl" per forzare la lingua.

Uso programmatico ​

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 viene interpretato come ora locale nel fuso timezone; il modulo la mostra esattamente come è stata indicata.

API dell'istanza ​

MembroDescrizione
id, typeID del widget e tipo di widget
getResult()L'ultimo risultato, sia che l'abbia calcolato il visitatore sia che l'abbia prodotto calculate()
setBirthData(data)Dati di nascita usati da calculate()
calculate()Esegue il calcolo da script e mostra il risultato. Supportato per natal, transit (al momento attuale), moonphase e moon-calendar (mese corrente); gli altri tipi ricevono i dati dal visitatore e restituiscono un rifiuto con errore
destroy()Smonta il widget

onResult si attiva per ogni risultato mostrato dal widget, per tutti i tipi di widget. AstroWidget.version indica la build del SDK.

Domini ​

allowedDomains limita i siti in cui la chiave API del widget funziona, confrontandola con l'Origin della richiesta del browser. Sono supportati i caratteri jolly per i sottodomini (*.example.com) e www. viene trattato come il dominio senza prefisso. Con l'elenco vuoto la chiave funziona su qualsiasi dominio, quindi compilalo prima di pubblicare il codice di incorporamento.

API del Widget ​

Questi sono gli endpoint che il SDK chiama per conto di un visitatore. Sono elencati per permetterti di costruire il tuo frontend su un widget; il SDK è il client di riferimento.

L'autenticazione è la chiave API del widget nell'header X-Api-Key. L'anteprima nella dashboard usa invece una sessione.

EndpointCorpoTipo di widget
GET /api/widget-api/config/:widgetId—qualsiasi; pubblico, restituisce widgetType e la customization già unita
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 } (nome e parti della data di nascita)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=—qualsiasi; ricerca di località per il modulo dei dati di nascita

birthData, person1 e person2 per i widget dei temi sono { dateTime, latitude, longitude, timezone, placeName? }, con dateTime come ora locale (1990-06-15T14:30:00) nel fuso timezone. Chiamare un endpoint per un widget di un altro tipo restituisce 400; un widget disabilitato restituisce 403; una richiesta da un dominio non incluso in allowedDomains restituisce 403 DOMAIN_NOT_ALLOWED.

Prossimi Passi ​

AstroAPI Documentation

Copyright © 2026 AstroAPI