PDF Reports

Generate professional PDF reports for natal charts, synastry, solar returns, and more. The PDF Reports module allows you to create customizable astrology reports with interpretations, charts, and tables.

Overview

The PDF Reports feature provides:

• Multiple report types: Natal, synastry, composite, transit, solar return, lunar return, progressions, numerology, and Chinese astrology
• Customizable templates: Create and manage your own PDF templates with custom layouts
• Automatic calculations: Astrology data is calculated on-the-fly and merged into your template
• Professional output: High-quality PDF generation with support for headers, footers, page numbers, and custom CSS

Supported Report Types

Report Type	Description
natal	Birth chart analysis with planetary positions, houses, and aspects
synastry	Relationship compatibility between two charts
composite	Combined chart for relationships
transit	Current planetary transits to natal chart
solar-return	Annual birthday chart
lunar-return	Monthly lunar return chart
progressions	Secondary progressions
numerology	Numerology calculations and analysis
chinese	Chinese astrology report

Generate a PDF Report

Generate a PDF report by providing birth data and optionally specifying a template.

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/generate" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "natal",
    "subject": {
      "name": "John Doe",
      "birthDate": {
        "year": 1990,
        "month": 6,
        "day": 15,
        "hour": 14,
        "minute": 30
      },
      "birthPlace": {
        "name": "London, UK",
        "latitude": 51.5074,
        "longitude": -0.1278,
        "timezone": "Europe/London"
      }
    }
  }' \
  --output natal-report.pdf

Request Parameters

Parameter	Type	Required	Description
reportType	string	Yes	Type of report (see supported types above)
templateId	string	No	Specific template ID to use (uses default if not provided)
subject	object	Yes	Birth data for the main subject
partner	object	No	Birth data for partner (required for synastry/composite)
transitDate	object	No	Target date for transit/return reports

Subject Object

Field	Type	Required	Description
name	string	Yes	Name of the person
birthDate	object	Yes	Birth date and time
birthDate.year	number	Yes	Birth year
birthDate.month	number	Yes	Birth month (1-12)
birthDate.day	number	Yes	Birth day (1-31)
birthDate.hour	number	Yes	Birth hour (0-23)
birthDate.minute	number	Yes	Birth minute (0-59)
birthPlace	object	Yes	Birth location
birthPlace.name	string	Yes	Location name
birthPlace.latitude	number	Yes	Latitude (-90 to 90)
birthPlace.longitude	number	Yes	Longitude (-180 to 180)
birthPlace.timezone	string	Yes	IANA timezone identifier

Response

The endpoint returns a PDF file (application/pdf) with the generated report.

Synastry Report Example

Generate a synastry report comparing two birth charts:

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/generate" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "synastry",
    "subject": {
      "name": "Person A",
      "birthDate": {
        "year": 1990,
        "month": 6,
        "day": 15,
        "hour": 14,
        "minute": 30
      },
      "birthPlace": {
        "name": "London, UK",
        "latitude": 51.5074,
        "longitude": -0.1278,
        "timezone": "Europe/London"
      }
    },
    "partner": {
      "name": "Person B",
      "birthDate": {
        "year": 1988,
        "month": 3,
        "day": 22,
        "hour": 9,
        "minute": 15
      },
      "birthPlace": {
        "name": "Paris, France",
        "latitude": 48.8566,
        "longitude": 2.3522,
        "timezone": "Europe/Paris"
      }
    }
  }' \
  --output synastry-report.pdf

Solar Return Report Example

Generate a solar return chart for a specific year:

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/generate" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "solar-return",
    "subject": {
      "name": "John Doe",
      "birthDate": {
        "year": 1990,
        "month": 6,
        "day": 15,
        "hour": 14,
        "minute": 30
      },
      "birthPlace": {
        "name": "London, UK",
        "latitude": 51.5074,
        "longitude": -0.1278,
        "timezone": "Europe/London"
      }
    },
    "transitDate": {
      "year": 2025,
      "month": 6,
      "day": 15,
      "hour": 0,
      "minute": 0
    }
  }' \
  --output solar-return-2025.pdf

Template Management

Templates define the layout and content of your PDF reports. Each template is associated with a specific report type.

List Templates

curl -X GET "https://api.astroapi.cloud/api/pdf-reports/templates" \
  -H "X-Api-Key: your-api-key"

Returns both organization-specific templates and global (shared) templates.

Get a Specific Template

curl -X GET "https://api.astroapi.cloud/api/pdf-reports/templates/{templateId}" \
  -H "X-Api-Key: your-api-key"

Create a Template

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/templates" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "templates",
      "attributes": {
        "name": "My Natal Report Template",
        "description": "Custom natal chart report",
        "reportType": "natal",
        "editorConfig": {},
        "pageSettings": {
          "format": "A4",
          "orientation": "portrait",
          "margins": {
            "top": 20,
            "right": 20,
            "bottom": 20,
            "left": 20
          }
        },
        "isDefault": true
      }
    }
  }'

Template Attributes

Attribute	Type	Description
name	string	Template name (1-100 characters)
description	string	Optional description
reportType	string	Report type this template is for
editorConfig	object	Editor.js block configuration
pageSettings	object	Page layout settings
customCss	string	Custom CSS styles
isDefault	boolean	Set as default for this report type
isActive	boolean	Whether the template is active

Page Settings

Setting	Type	Description
format	string	Page size: "A4" or "Letter"
orientation	string	"portrait" or "landscape"
margins	object	Page margins in mm (top, right, bottom, left)
header	object	Header configuration
footer	object	Footer configuration
pageNumbers	object	Page number settings

Header/Footer Configuration

{
  "header": {
    "enabled": true,
    "height": 15,
    "content": "My Astrology Report"
  },
  "footer": {
    "enabled": true,
    "height": 15,
    "content": "Generated by AstroAPI"
  },
  "pageNumbers": {
    "enabled": true,
    "position": "bottom-center",
    "format": "Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span>"
  }
}

Update a Template

curl -X PATCH "https://api.astroapi.cloud/api/pdf-reports/templates/{templateId}" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "templates",
      "attributes": {
        "name": "Updated Template Name"
      }
    }
  }'

Delete a Template

curl -X DELETE "https://api.astroapi.cloud/api/pdf-reports/templates/{templateId}" \
  -H "X-Api-Key: your-api-key"

Duplicate a Template

Copy an existing template (including global templates) to your organization:

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/templates/{templateId}/duplicate" \
  -H "X-Api-Key: your-api-key"

Set Default Template

Set a template as the default for its report type:

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/templates/{templateId}/set-default" \
  -H "X-Api-Key: your-api-key"

Preview a Template

Preview how a template will render with sample data (returns HTML):

curl -X POST "https://api.astroapi.cloud/api/pdf-reports/preview" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id"
  }'

Template Resolution

When generating a PDF, the system resolves which template to use in this order:

1. Specific template: If templateId is provided in the request
2. Organization default: The organization's default template for the report type
3. Global default: A global (shared) default template for the report type

Required Permissions

Endpoint	Permission
List/Get templates	content:read
Generate PDF	content:read
Preview template	content:read
Create template	content:create
Update template	content:update
Delete template	content:delete
Duplicate template	content:create
Set default	content:update

Report Content

Generated reports include:

• Subject information: Name, birth date, time, and location
• Planetary positions: All major planets with sign, house, and degree
• House cusps: All 12 house cusps with signs
• Aspects: Planetary aspects with orbs and interpretations
• Interpretations: CMS-sourced text content for each placement and aspect

The actual content depends on the template configuration and available CMS content.