Official n8n community node for Astrology API — professional astrological calculations powered by Swiss Ephemeris.
- Planetary Positions — Get positions with zodiac signs, degrees, and retrograde status
- House Cusps — Calculate house boundaries (23+ house systems supported)
- Aspects — Angular relationships between celestial bodies
- Lunar Metrics — Moon phases, illumination, and void-of-course periods
- Current Time Data — Real-time astrological data for current moment
- Sign-based Horoscopes — Daily, weekly, monthly, yearly predictions by zodiac sign
- Personal Horoscopes — Customized predictions based on birth chart
- Chinese Bazi — Four Pillars of Destiny analysis
- Multiple Traditions — Western, Vedic, Chinese astrology support
- Multi-language — EN, RU, UK, ES, DE, FR and more
- Natal Charts — Birth chart generation with SVG output
- Transit Charts — Current planetary transits overlay on natal chart
- Synastry Charts — Relationship compatibility analysis (cross-aspects)
- Composite Charts — Merged midpoint chart for couples
- Solar Return Charts — Birthday year forecast
- Lunar Return Charts — Monthly forecast based on Moon return
- Progressions Charts — Secondary progressions for life phases
- Natal Transits — Transit analysis over date range
- Directions Charts — Primary directions for timing predictions
- Multiple House Systems — Placidus, Koch, Equal, Whole Sign, and 20+ more
- Open your n8n instance
- Go to Settings → Community Nodes
- Select Install
- Enter
@astro-api/n8n-nodes-astrology - Click Install
npm install @astro-api/n8n-nodes-astrologyFor Docker deployments, mount the package or use N8N_CUSTOM_EXTENSIONS.
- Get your API key at astrology-api.io
- In n8n, go to Credentials → New Credential
- Select Astrology API
- Enter your API key
- (Optional) Configure custom base URL if using self-hosted API
| Variable | Description | Default |
|---|---|---|
| — | API key is stored in n8n credentials | — |
- Install the node via Settings → Community Nodes →
@astro-api/n8n-nodes-astrology - Add Astrology API credentials with your API key from astrology-api.io
- Add the Astrology node to your workflow
- Select a resource and operation from the table below
- Configure the required parameters and execute
| Use Case | Resource | Operation | What You Get |
|---|---|---|---|
| Planet positions | Data | Positions | Zodiac signs, degrees, retrograde status for each planet |
| House boundaries | Data | House Cusps | Astrological house boundaries (23+ house systems) |
| Planetary aspects | Data | Aspects | Angular relationships between celestial bodies |
| Moon data | Data | Lunar Metrics | Moon phase, illumination, void-of-course periods |
| Current sky | Data | Current Time | Real-time astrological data for the current moment |
| Daily horoscope | Horoscope | Sign Daily | Daily prediction for any zodiac sign |
| Weekly horoscope | Horoscope | Sign Weekly | Weekly prediction for any zodiac sign |
| Monthly horoscope | Horoscope | Sign Monthly | Monthly prediction for any zodiac sign |
| Yearly horoscope | Horoscope | Sign Yearly | Yearly prediction for any zodiac sign |
| Personal forecast | Horoscope | Personal Daily/Weekly/Monthly/Yearly | Birth chart-based personalized predictions |
| Chinese astrology | Horoscope | Chinese Bazi | Four Pillars of Destiny analysis |
| Birth chart | Charts | Natal | SVG natal chart with configurable house system |
| Relationship chart | Charts | Synastry | Two-person compatibility analysis (cross-aspects) |
| Combined chart | Charts | Composite | Merged midpoint chart for couples |
| Current transits | Charts | Transit | Planetary transits overlay on natal chart |
| Birthday forecast | Charts | Solar Return | Year-ahead predictions based on Sun return |
| Monthly forecast | Charts | Lunar Return | Month-ahead predictions based on Moon return |
| Life phases | Charts | Progressions | Secondary progressions for internal development |
| Period analysis | Charts | Natal Transits | Transit events over a date range |
| Timing predictions | Charts | Directions | Primary directions for life event timing |
Planetary Positions & Birth Data Configure Data → Positions to calculate planetary positions for any date and location. Returns zodiac signs, degrees, minutes, and retrograde status. Supports both city-based and coordinate-based location input.
Horoscopes in Multiple Languages Use Horoscope → Sign Daily/Weekly/Monthly/Yearly for zodiac sign predictions. Supports multiple languages (EN, RU, UK, ES, DE, FR) and traditions (Western, Vedic, Chinese).
Personal Horoscopes Use Horoscope → Personal Daily/Weekly/Monthly/Yearly for customized predictions based on birth chart data. Combines natal positions with current transits for personalized forecasts.
Natal Chart Generation Generate SVG birth charts with Charts → Natal. Supports 23+ house systems including Placidus, Koch, Equal, and Whole Sign.
Import complete workflow examples from the examples/ folder:
- AI Astrologer Assistant — AI-powered chatbot with multiple Astrology tools. Demonstrates using the node with n8n AI Agent for conversational astrology queries.
- Personal Horoscope Workflow — Generates personalized horoscopes (day/week/month/year) by comparing natal chart with current transits. Includes AI interpretation.
- Tarot Reading Workflow — Performs tarot card readings influenced by current planetary positions and moon phase. Supports multiple spread types.
The Astrology node supports AI Tool mode via n8n's usableAsTool feature. This allows you to connect the node to an AI Agent for conversational astrology queries.
When usableAsTool: true is set, n8n automatically generates a companion Tool node:
| Node Type | Purpose | Connection Type |
|---|---|---|
astrology |
Standard workflow node | main → main |
astrologyTool |
AI Tool for Agent | ai_tool → ai_tool |
When building workflows with AI Agent:
- Use the Tool version — In workflow JSON, use type
@astro-api/n8n-nodes-astrology.astrologyTool - Connect via
ai_tool— Connect nodes to AI Agent usingai_toolconnection type - Use
$fromAI()expressions — Let AI extract parameters automatically
Example node configuration:
{
"parameters": {
"year": "={{ $fromAI('year', 'Birth year (e.g., 1990)') }}",
"month": "={{ $fromAI('month', 'Month 1-12') }}",
"city": "={{ $fromAI('city', 'City name') }}"
},
"type": "@astro-api/n8n-nodes-astrology.astrologyTool"
}Example connection:
"Planetary Positions": {
"ai_tool": [[{"node": "AI Agent", "type": "ai_tool", "index": 0}]]
}See AI Astrologer Assistant for a complete working example.
Full API documentation is available at:
- Interactive Docs: api.astrology-api.io/rapidoc
- Postman Collection: Download
- Node.js v20+
- npm or pnpm
git clone https://github.com/astro-api/n8n-nodes-astrology.git
cd n8n-nodes-astrology
npm install
npm run buildPre-commit hooks automatically run on staged files:
- ESLint — linting with auto-fix
- Prettier — code formatting
Available scripts:
npm run lint # Check for lint errors
npm run lint:fix # Fix lint errors
npm run format # Format code
npm run format:check # Check formattingnpm run build
cd docker && docker compose upAccess n8n at http://localhost:5678
├── credentials/ # API credential definitions
├── nodes/Astrology/
│ ├── handlers/ # Execute logic by resource
│ ├── interfaces/ # TypeScript types
│ ├── operations/ # UI parameter definitions
│ └── shared/ # Reusable fields and helpers
└── dist/ # Compiled output
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
When you make changes that should be included in a release:
npx changesetSelect the change type:
- patch (0.1.0 → 0.1.1) — bug fixes
- minor (0.1.0 → 0.2.0) — new features
- major (0.1.0 → 1.0.0) — breaking changes
Commit the generated changeset file along with your code.
This project uses Changesets for version management and GitHub Actions for CI/CD.
| Workflow | Trigger | Actions |
|---|---|---|
| CI | Push/PR to master |
Lint, Build, Verify dist |
| Release | Push to master |
Create release PR or publish to npm |
- Development: Create PR with code changes + changeset file
- Merge to master: CI validates, then Release workflow creates a "chore: release package" PR
- Release PR: Contains version bump + CHANGELOG update
- Merge Release PR: Triggers npm publish + GitHub Release creation
- Documentation: astrology-api.io/docs
- Issues: GitHub Issues
- Email: support@astrology-api.io
MIT License — see LICENSE for details.
Made with ☿ by Astrology API