AstroAPI

Appearance

Widgets Intégrables ​

Créez et gérez des widgets intégrables pour votre site web. Un widget est un composant UI prêt à l'emploi dédié à une seule fonctionnalité astrologique : un formulaire de thème natal, un calendrier lunaire, un sélecteur d'horoscope quotidien. Vous le configurez dans le tableau de bord ou via cette API, puis vous le placez sur n'importe quelle page avec une seule balise script.

Deux API, deux clés

  • L'API de gestion (/api/widgets) crée et configure les widgets. Elle utilise votre clé API habituelle.
  • L'API widget (/api/widget-api) est celle que le SDK appelle depuis le navigateur du visiteur. Elle utilise la clé propre au widget, que l'on peut placer sans risque dans une page puisqu'elle est limitée à ce seul widget.

Vous cherchez le guide sans code ? Voir Ajouter des widgets à votre site web.

Types de Widgets ​

Les types de widgets que vous pouvez créer dépendent des modules de votre organisation. GET /api/widgets/options liste ceux qui vous sont accessibles.

TypeDescriptionModules requis
natalFormulaire de données de naissance avec thème, positions et aspectsmodule:natal
synastryDeux formulaires de données de naissance, thème de synastrie et aspects croisésmodule:natal, module:synastry
transitDonnées de naissance et moment de transit, thème en double rouemodule:natal, module:transits
compositeDeux formulaires de données de naissance, thème compositemodule:natal, module:composite
moonphasePhase lunaire actuelle avec taux d'illuminationmodule:moon
daily-horoscopeSélecteur de signe avec l'horoscope du jourmodule:daily-report
numerologyFormulaire nom et date de naissance avec les nombres principauxmodule:numerology
compatibilityDeux personnes, score de compatibilité numérologiquemodule:numerology, module:compatibility
moon-calendarCalendrier mensuel avec phases, lever et coucher de lunemodule:moon

Gestion des Widgets ​

Tous les endpoints de gestion sont au format JSON:API et utilisent le type de ressource widget.

Lister les Widgets ​

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

Obtenir un Widget ​

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

Créer 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 réponse à une création est le seul moment où la clé API complète du widget est renvoyée (apiKey). Conservez-la, ou régénérez-la plus tard ; toutes les autres réponses ne contiennent que 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_..." } }
        }
    }
}

Mettre à Jour un Widget ​

PATCH accepte n'importe quel sous-ensemble de name, enabled, allowedDomains et customization. La personnalisation est remplacée dans son intégralité : envoyez donc l'objet complet.

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

Supprimer un Widget ​

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

Régénérer la clé API du widget ​

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

Renvoie le widget avec une nouvelle apiKey. Mettez à jour le code d'intégration sur votre site avec la nouvelle clé ; l'identifiant du widget reste inchangé.

Options de Widget Disponibles ​

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

Fonctionnalités du Forfait ​

FonctionnalitéDescription
canRemoveBrandingbranding.showPoweredBy peut valoir false
canUseCustomLogobranding.logoUrl et branding.companyName peuvent être définis
canUseCustomCsscustomCss est transmis au widget
maxDomainsNombre maximal de allowedDomains par widget, ou "unlimited"

Objet de Personnalisation ​

Chaque champ est facultatif ; ce que vous omettez est complété par les valeurs par défaut ci-dessous au moment où le widget est servi. Les couleurs sont des chaînes de couleur CSS, les tailles des nombres en pixels.

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

Champs de Personnalisation ​

ChampTypeDescription
colors.*stringDix couleurs CSS, appliquées au widget sous forme de variables CSS
fonts.familystringValeur CSS font-family
fonts.sizeBase / sizeHeading / sizeSmallnumberTailles de police en pixels
fonts.weightNormal / weightBoldnumberGraisses de police
borders.radius / widthnumberPixels ; utilisés par les champs de saisie, les boutons et la mise en page en carte
borders.stylestringsolid, dashed, dotted ou none
spacing.padding / marginnumberPixels ; les mises en page card et compact utilisent padding
shadows.presetstringnone, sm, md, lg ou xl (mise en page en carte)
shadows.customstring | nullUn box-shadow CSS qui remplace le préréglage
layout.variantstringVoir Variantes de mise en page
interaction.tooltipEnabledbooleanInfobulles au survol des lignes de planètes, des lignes d'aspects et des jours du calendrier
interaction.animationsEnabledbooleanAnimations d'apparition ; toujours désactivées pour les visiteurs qui préfèrent les mouvements réduits
interaction.clickThroughEnabledbooleanTransforme le thème affiché en lien vers clickThroughUrl
interaction.clickThroughUrlstring | nullS'ouvre dans un nouvel onglet
chartSettingsobjectUn thème de thème astral partiel appliqué par-dessus le thème par défaut : couleurs par signe, point et aspect, épaisseurs de trait, showDegrees, showRetrograde, etc.
labelsobjectRemplacements pour n'importe quelle clé de libellé ; voir Langues et libellés
languagestringL'un des 13 codes de langue pris en charge
branding.showPoweredBybooleanNécessite canRemoveBranding pour être mis à false
branding.logoUrl / companyNamestring | nullNécessitent canUseCustomLogo
customCssstring | nullInjecté dans la page pour le widget ; nécessite canUseCustomCss
widgetOptions.showAspects / showPointsbooleanAffiche les tableaux des aspects et des positions sous un thème
widgetOptions.showHousesbooleanAffiche les numéros de maison sur le thème
widgetOptions.chartSizestring | numbersmall (300), medium (450), large (600) ou une largeur en pixels
widgetOptions.themestringlight, dark, cosmic, custom ou auto
numerologyOptions.*booleanLes nombres que le widget de numérologie affiche
dailyHoroscopeOptions.autoRefreshbooleanRéservé
moonCalendarOptions.*booleanLes détails affichés par un jour du calendrier et les phases mises en évidence
compatibilityOptions.*booleanAnneau de score, description et nombres de chemin de vie

Variantes de mise en page ​

ValeurDescription
cardSurface encadrée avec le rayon, le remplissage et l'ombre configurés (par défaut)
compactMoitié moins de remplissage et une typographie légèrement plus petite, pour les barres latérales
fullD'un bord à l'autre, remplissage vertical uniquement
minimalAucun cadre ; tout est hérité de la page

Thèmes ​

light, dark et cosmic sont des palettes fixes pour les surfaces et les bordures. auto utilise la palette claire et bascule vers la palette sombre lorsque le système du visiteur préfère le sombre. custom ne définit rien et s'appuie sur vos colors. Dans tous les thèmes, les dix colors que vous définissez l'emportent sur la palette.

Langues et libellés ​

Le SDK fournit des libellés pour en, nl, de, fr, es, es-419, it, pt, pt-BR, tr, ru, ja et zh-CN. Les variantes régionales retombent sur leur langue de base pour tout ce qu'elles ne redéfinissent pas. labels remplace des chaînes individuelles par-dessus la langue choisie, par exemple :

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

La langue peut aussi être définie page par page : data-lang="de" sur la balise script, ou ?lang=de dans l'URL de la page ; les deux priment sur la langue enregistrée.

Intégrer un Widget ​

Le SDK est servi depuis https://widgets.astroapi.cloud/sdk.js. L'onglet Embed du tableau de bord produit les deux extraits ci-dessous avec vos identifiants déjà renseignés.

Initialisation automatique ​

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>

Attributs facultatifs : data-container="#my-element" pour effectuer le rendu ailleurs que dans le div par défaut, et data-lang="nl" pour remplacer la langue.

Par programmation ​

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 est interprété comme une heure locale dans timezone ; le formulaire l'affiche exactement telle qu'elle est fournie.

API d'Instance ​

MembreDescription
id, typeIdentifiant et type du widget
getResult()Le dernier résultat, que le visiteur l'ait calculé ou que ce soit calculate()
setBirthData(data)Données de naissance utilisées par calculate()
calculate()Lance le calcul depuis le script et affiche le résultat. Pris en charge pour natal, transit (au moment présent), moonphase et moon-calendar (mois en cours) ; les autres types prennent leur saisie auprès du visiteur et renvoient une erreur
destroy()Retire le widget de la page

onResult se déclenche pour chaque résultat affiché par le widget, quel que soit son type. AstroWidget.version indique la version compilée du SDK.

Domaines ​

allowedDomains limite les emplacements où la clé API du widget fonctionne, en la vérifiant par rapport à l'Origin de la requête du navigateur. Les jokers de sous-domaine (*.example.com) sont pris en charge et www. est traité comme le domaine nu. Avec une liste vide, la clé fonctionne sur n'importe quel domaine : renseignez-la donc avant de publier le code d'intégration.

API Widget ​

Voici les endpoints que le SDK appelle pour le compte d'un visiteur. Ils sont listés ici pour que vous puissiez construire votre propre interface au-dessus d'un widget ; le SDK est le client de référence.

L'authentification se fait avec la clé API du widget dans X-Api-Key. L'aperçu du tableau de bord utilise une session à la place.

EndpointCorpsType de widget
GET /api/widget-api/config/:widgetId—tous ; public, renvoie widgetType et la customization fusionnée
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 } (nom et éléments de la date de naissance)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=—tous ; recherche de lieu pour le formulaire de données de naissance

Pour les widgets de thème astral, birthData, person1 et person2 valent { dateTime, latitude, longitude, timezone, placeName? }, où dateTime est une heure locale (1990-06-15T14:30:00) dans timezone. Appeler un endpoint pour un widget d'un autre type renvoie 400 ; un widget désactivé renvoie 403 ; une requête provenant d'un domaine absent de allowedDomains renvoie 403 DOMAIN_NOT_ALLOWED.

Étapes Suivantes ​

AstroAPI Documentation

Copyright © 2026 AstroAPI