@astro-api/n8n-nodes-astrology

Official n8n community node for Astrology API — professional astrological calculations powered by Swiss Ephemeris.

Features

Data & Calculations

• 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

Horoscopes & Predictions

• 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

Charts & Visualization

• Natal Charts — Birth chart generation with SVG output
• Transit Charts — Current planetary transits overlay
• Synastry — Relationship compatibility analysis
• Multiple House Systems — Placidus, Koch, Equal, Whole Sign, and 20+ more

Installation

n8n Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Select Install
4. Enter @astro-api/n8n-nodes-astrology
5. Click Install

Manual Installation

npm install @astro-api/n8n-nodes-astrology

For Docker deployments, mount the package or use N8N_CUSTOM_EXTENSIONS.

Configuration

API Credentials

1. Get your API key at astrology-api.io
2. In n8n, go to Credentials → New Credential
3. Select Astrology API
4. Enter your API key
5. (Optional) Configure custom base URL if using self-hosted API

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | — | API key is stored in n8n credentials | — |

Usage Examples

Quick Start

1. Install the node via Settings → Community Nodes → @astro-api/n8n-nodes-astrology
2. Add Astrology API credentials with your API key from astrology-api.io
3. Add the Astrology node to your workflow
4. Select a resource and operation from the table below
5. Configure the required parameters and execute

Operations Overview

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

Common Use Cases

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.

Ready-to-Use Workflows

Import complete workflow examples from the examples/ folder:

• 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.

API Documentation

Full API documentation is available at:

• Interactive Docs: api.astrology-api.io/rapidoc
• Postman Collection: Download

Development

Prerequisites

• Node.js v20+
• npm or pnpm

Setup

git clone https://github.com/astro-api/n8n-nodes-astrology.git
cd n8n-nodes-astrology
npm install
npm run build

Code Quality

Pre-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 formatting

Testing with Docker

npm run build
cd docker && docker compose up

Access n8n at http://localhost:5678

Project Structure

├── 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

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Creating a Changeset

When you make changes that should be included in a release:

npx changeset

Select 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.

Release Process

This project uses Changesets for version management and GitHub Actions for CI/CD.

Automated Pipeline

| Workflow | Trigger | Actions | |----------|---------|---------| | CI | Push/PR to master | Lint, Build, Verify dist | | Release | Push to master | Create release PR or publish to npm |

How Releases Work

1. Development: Create PR with code changes + changeset file
2. Merge to master: CI validates, then Release workflow creates a "chore: release package" PR
3. Release PR: Contains version bump + CHANGELOG update
4. Merge Release PR: Triggers npm publish + GitHub Release creation

Support

• Documentation: astrology-api.io/docs
• Issues: GitHub Issues
• Email: [email protected]

License

MIT License — see LICENSE for details.

Made with ☿ by Astrology API