Volver a la documentación

Generador de cartas SVG/PNG

Generador de cartas SVG/PNG

POST/api/v1/natal/chart/

Genera visualizaciones de cartas natales personalizables en SVG o PNG de alta resolución. Control completo de colores, tamaños, cuerpos celestes y estilos visuales.

La hora de nacimiento desconocida está admitida con time_known: false; casas y ángulos se omiten en ese modo.

Endpoints SVG relacionados

Usa el endpoint natal de rueda simple para una persona. Para cartas relacionales, la familia SVG también incluye variantes composite midpoint y sinastría.

Carta SVG compuesta
Composite midpoint en rueda única construido a partir de dos personas.
Carta SVG de sinastría
Carta de compatibilidad de dos ruedas con ambas personas superpuestas.

Ejemplo de salida

Ejemplo natal estándar
Example natal chart generated by the API
Ejemplo de estilo francés
Carta natal de estilo francés generada por la API con la carta SVG por defecto

SVG real generado por la API con la carta por defecto y chart_config.french_style: true.

Superposición de forma de horóscopo

Define chart_config.show_horoscope_shape como true para detectar la forma de distribución de la carta a partir solo de los 10 planetas. Cuando se detecta una forma, la malla central de aspectos se oculta y se reemplaza por una geometría sólida y legible.

Carta natal SVG con superposición de forma bucket renderizada en el disco central

Salida API real

Este SVG fue generado por POST /api/v1/natal/chart/ con una forma Bucket detectada. La respuesta incluye data-key="horoscope_shape.bucket" y metadatos JSON opcionales en freeastroapi-horoscope-shape.

Usa estos campos de chart_config

show_horoscope_shapehoroscope_shape_stylehoroscope_shape_colorhoroscope_shape_labelembed_horoscope_shape_metadata

Formas admitidas y reglas de detección

Bundle
Los 10 planetas caben dentro de un arco ocupado de 120°.
Bucket
Un planeta asa, o un pequeño cluster asa de dos planetas, queda fuera del grupo principal. Los otros planetas deben caber en 181°, sin ancho mínimo de cluster; el cluster asa no debe superar 15°, el asa debe estar al menos a 30° del grupo principal y la carta completa debe superar un arco único de 180°.
Bowl
Los 10 planetas ocupan un arco continuo superior a 120° e inferior o igual a 210°, con un gran vacío de al menos 150°. Si un planeta o un pequeño cluster de dos planetas se separa como asa, Bucket tiene prioridad.
See-Saw
Dos clusters separados, con el mayor vacío de al menos 90° y el segundo mayor vacío de al menos 50°.
Locomotive
Los planetas ocupan más de 210° y como máximo 260°, dejando un vacío director desde 100° hasta, sin incluirlo, 150°.
Splash
Distribution large sans grand vide : les deux plus grands espaces interplanetaires sont tous deux inferieurs a 60°.

La detección de forma usa solo Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune y Pluto. Los ángulos, nodos, asteroides, Lilith, Chiron y lotes no afectan la forma detectada.

Superposición de configuraciones de aspectos

Usa chart_config.show_pattern_overlays para renderizar estructuras de aspectos detectadas directamente en la carta. Las superposiciones de configuración mantienen visible el círculo normal de aspectos y añaden subcapas, trazos, etiquetas y atributos SVG estables para la interacción con la interfaz.

Carta natal SVG con una sola superposición filtrada de configuración de aspecto Grand Cross

Salida API real

Este SVG muestra únicamente una superposición Grand Cross filtrada, correspondiente a una configuración con pattern_overlay_types definido como grand_cross y pattern_overlay_max_items definido como 1. Los elementos renderizados incluyen atributos como data-pattern-type, data-bodies y data-key="pattern.*" para que tu UI pueda resaltar, filtrar o explicar la estructura seleccionada.

Usa estos campos de chart_config

show_pattern_overlayspattern_overlay_typespattern_overlay_stylepattern_overlay_labelspattern_overlay_max_itemsembed_pattern_metadata

Las estructuras renderizadas admitidas incluyen grand_trine, t_square, yod, kite, grand_cross, minor_grand_trine, wedge, mystic_rectangle, cradle, castle, grand_sextile y stellium.

Galería de vistas previas de temas

Tres temas de cartas de estilo producción renderizados desde preajustes API. Las imágenes son vistas previas WebP optimizadas para mostrar calidad y rendimiento.

Vista previa del tema de carta astrológica Classic Clarity

Classic Clarity

Perfil de consulta equilibrado con jerarquía de líneas contenida.

Vista previa del tema de carta astrológica Navy Gold

Navy Gold

Paleta oscura premium con alta legibilidad simbólica.

Vista previa del tema de carta astrológica Slate Mineral

Slate Mineral

Paleta neutra gris frío para lectura técnica de la carta.

Preajustes editoriales de temas (solo colores)

Estos preajustes usan únicamente los parámetros de solicitud existentes. No requieren ningún cambio interno del motor de renderizado.

Ivory Ink

Paleta editorial clara con tonos cálidos de papel y contraste de tinta contenido.

{
  "name": "Theme: Ivory Ink",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "London",
  "lat": 51.5,
  "lng": -0.12,
  "tz_str": "UTC",
  "format": "png",
  "theme_type": "light",
  "chart_config": {
    "chart_background": "#F6F1E8",
    "custom_planet_color": "#1E1B18",
    "custom_sign_color": "#6A5B48",
    "custom_house_color": "#3E362C",
    "custom_sign_bg_color": "#EFE4D3",
    "custom_house_bg_color": "#FAF6EE",
    "sign_line_color": "#3A3128",
    "house_line_color": "#8C7C68",
    "aspect_conjunction_color": "#2F2A24",
    "aspect_opposition_color": "#A1362A",
    "aspect_trine_color": "#1F4E79",
    "aspect_square_color": "#8F2B23",
    "aspect_sextile_color": "#355E8D",
    "aspect_quincunx_color": "#4D6A3A"
  }
}

Navy Gold

Paleta oscura premium con base navy y símbolos/líneas doradas suavizadas.

{
  "name": "Theme: Navy Gold",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "London",
  "lat": 51.5,
  "lng": -0.12,
  "tz_str": "UTC",
  "format": "png",
  "theme_type": "dark",
  "chart_config": {
    "chart_background": "#0D1B2A",
    "custom_planet_color": "#E7D3A5",
    "custom_sign_color": "#C9B27C",
    "custom_house_color": "#A7B8C9",
    "custom_sign_bg_color": "#14263B",
    "custom_house_bg_color": "#102034",
    "sign_line_color": "#D8C08A",
    "house_line_color": "#60758D",
    "aspect_conjunction_color": "#D6DCE5",
    "aspect_opposition_color": "#E06C5B",
    "aspect_trine_color": "#6EA8FF",
    "aspect_square_color": "#C85C53",
    "aspect_sextile_color": "#7EB7FF",
    "aspect_quincunx_color": "#7EBB8D"
  }
}

Slate Mineral

Paleta neutra gris frío con acentos de aspectos azul-verde mineral.

{
  "name": "Theme: Slate Mineral",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "London",
  "lat": 51.5,
  "lng": -0.12,
  "tz_str": "UTC",
  "format": "png",
  "theme_type": "light",
  "chart_config": {
    "chart_background": "#E9EDF1",
    "custom_planet_color": "#22313F",
    "custom_sign_color": "#3F5D73",
    "custom_house_color": "#4D5B66",
    "custom_sign_bg_color": "#DCE4EA",
    "custom_house_bg_color": "#EEF2F6",
    "sign_line_color": "#2F3D49",
    "house_line_color": "#7D8C98",
    "aspect_conjunction_color": "#3A4955",
    "aspect_opposition_color": "#B04A3B",
    "aspect_trine_color": "#2B6F9C",
    "aspect_square_color": "#9A3E33",
    "aspect_sextile_color": "#3D7FAF",
    "aspect_quincunx_color": "#4A7A63"
  }
}

Classic Clarity

Base de consulta profesional con jerarquía de líneas contenida y malla de aspectos más nítida.

{
  "name": "Theme: Classic Clarity",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "London",
  "lat": 51.5,
  "lng": -0.12,
  "tz_str": "UTC",
  "format": "png",
  "theme_type": "light",
  "chart_config": {
    "sign_line_width": 1.6,
    "house_line_width": 0.9,
    "asc_line_width": 2.4,
    "dsc_line_width": 2.4,
    "mc_line_width": 2.4,
    "ic_line_width": 2.4,
    "sign_ring_inner_width": 1.2,
    "sign_ring_outer_width": 1.6,
    "house_ring_inner_width": 0.8,
    "house_ring_outer_width": 0.9,
    "sign_tick_width": 0.45,
    "aspect_conjunction_width": 2.2,
    "aspect_opposition_width": 2.2,
    "aspect_trine_width": 1.8,
    "aspect_square_width": 2.0,
    "aspect_sextile_width": 1.5,
    "aspect_quincunx_width": 1.3
  }
}

Dense Analysis

Perfil técnico avanzado con ejes, anillos y aspectos más fuertes para lectura detallada.

{
  "name": "Theme: Dense Analysis",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "London",
  "lat": 51.5,
  "lng": -0.12,
  "tz_str": "UTC",
  "format": "png",
  "theme_type": "light",
  "chart_config": {
    "sign_line_width": 2.6,
    "house_line_width": 1.35,
    "asc_line_width": 3.6,
    "dsc_line_width": 3.6,
    "mc_line_width": 3.6,
    "ic_line_width": 3.6,
    "sign_ring_inner_width": 1.9,
    "sign_ring_outer_width": 2.6,
    "house_ring_inner_width": 1.2,
    "house_ring_outer_width": 1.3,
    "sign_tick_width": 0.62,
    "aspect_conjunction_width": 3.2,
    "aspect_opposition_width": 3.2,
    "aspect_trine_width": 2.6,
    "aspect_square_width": 2.9,
    "aspect_sextile_width": 2.3,
    "aspect_quincunx_width": 2.0
  }
}

URL completa

https://api.freeastroapi.com/api/v1/natal/chart/

Parámetros básicos

Parámetro
name
Type
string
Requis
Sí
Defaut
-
Description
Nombre del sujeto (se muestra en los metadatos)
Parámetro
year
Type
integer
Requis
Sí
Defaut
-
Description
Año de nacimiento (ex. 1990)
Parámetro
month
Type
integer
Requis
Sí
Defaut
-
Description
Mes de nacimiento (1-12)
Parámetro
day
Type
integer
Requis
Sí
Defaut
-
Description
Día de nacimiento (1-31)
Parámetro
hour
Type
integer
Requis
Sí
Defaut
-
Description
Hora de nacimiento (0-23, formato 24 h)
Parámetro
minute
Type
integer
Requis
Sí
Defaut
-
Description
Minuto de nacimiento (0-59)
Parámetro
time_known
Type
boolean
Requis
No
Defaut
true
Description
Define false cuando se desconoce la hora de nacimiento. En este modo, casas y ángulos se omiten de la carta.
Parámetro
city
Type
string
Requis
No
Defaut
-
Description
Nombre de ciudad. Opcional cuando se proporcionan lat/lng; se usa para buscar coordenadas cuando se omiten.
Parámetro
lat
Type
float
Requis
No
Defaut
auto
Description
Latitud (-90 a 90). Requerida con lng si se omite city.
Parámetro
lng
Type
float
Requis
No
Defaut
auto
Description
Longitud (-180 a 180). Requerida con lat si se omite city.
Parámetro
tz_str
Type
string
Requis
No
Defaut
AUTO
Description
Zona horaria (ej. 'Europe/Paris' o 'AUTO')
Parámetro
house_system
Type
string
Requis
No
Defaut
placidus
Description
placidus, whole_sign, equal, koch, etc.
Parámetro
zodiac_type
Type
string
Requis
No
Defaut
tropical
Description
tropical o sidereal
Parámetro
sidereal_ayanamsa
Type
string
Requis
No
Defaut
lahiri
Description
lahiri, raman, kp, etc. (solo sidereal)

Parámetros de salida de la carta

Parámetro
format
Type
string
Requis
No
Defaut
svg
Description
Formato de salida: 'svg' o 'png'
Parámetro
size
Type
integer
Requis
No
Defaut
700
Description
Anchura/altura de la carta en píxeles
Parámetro
theme_type
Type
string
Requis
No
Defaut
light
Description
Tema: 'light', 'dark' o 'mono'
Parámetro
png_quality_scale
Type
float
Requis
No
Defaut
2.0
Description
Multiplicador de resolución PNG (1.0-5.0)
Parámetro
show_metadata
Type
boolean
Requis
No
Defaut
true
Description
Mostrar el bloque de metadatos (nombre, fecha, lugar)
Parámetro
display_settings
Type
object
Requis
No
Defaut
{}
Description
Controles de visibilidad por cuerpo para planetas, ángulos y puntos opcionales.
Parámetro
chart_config
Type
object
Requis
No
Defaut
{}
Description
Sobrescrituras avanzadas de estilo visual y layout. Consulta la sección de configuración de carta más abajo para los campos admitidos.

Estrellas fijas

Las estrellas fijas solicitadas en los SVG de carta se renderizan en la misma rueda de cuerpos que planetas y puntos, con una etiqueta de tres letras como Reg o Ald. Las líneas de aspectos son opcionales mediante chart_config.show_fixed_star_aspects y por defecto se limitan a conjunciones cerradas.

Parámetro
fixed_stars
Type
array<string>
Requis
No
Defaut
[]
Description
Selector de estrellas fijas renderizadas en la rueda de cuerpos. Acepta ids de packs como royal_4 y behenian_20, nombres exactos como Spica o Regulus, o all para el conjunto completo por defecto.
Parámetro
chart_config.fixed_star_color
Type
string
Requis
No
Defaut
theme points color
Description
Color de etiquetas, conectores y líneas de aspectos de estrellas fijas activadas.
Parámetro
chart_config.show_fixed_star_aspects
Type
boolean
Requis
No
Defaut
false
Description
Activa las líneas de aspectos de estrellas fijas.
Parámetro
chart_config.fixed_star_aspect_types
Type
array<string>
Requis
No
Defaut
['conjunction']
Description
Tipos de aspectos que se dibujan para las estrellas fijas. Admite conjunction, opposition, trine, square, sextile, quincunx.
Parámetro
chart_config.fixed_star_aspect_orb
Type
float
Requis
No
Defaut
1.0
Description
Orbe en grados para aspectos de estrellas fijas.

Las 20 estrellas clásicas/behenianas

La lista completa de estrellas fijas importantes para flujos de astrología tradicional.

"fixed_stars": ["behenian_20"]

Las 4 estrellas reales

Regulus, Aldebaran, Antares y Fomalhaut.

"fixed_stars": ["royal_4"]
{
  "name": "Natal Chart with Royal Fixed Stars",
  "year": 1990,
  "month": 5,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "city": "London",
  "lat": 51.5,
  "lng": -0.12,
  "tz_str": "UTC",
  "format": "svg",
  "theme_type": "light",
  "fixed_stars": ["royal_4"],
  "chart_config": {
    "degree_label_format": "minutes",
    "show_planet_connectors": true,
    "show_fixed_star_aspects": true,
    "fixed_star_aspect_types": ["conjunction"],
    "fixed_star_aspect_orb": 1.0,
    "fixed_star_color": "#A16207"
  }
}

Parámetros de visualización (objeto display_settings)

Controla los cuerpos celestes que aparecen en la carta:

Parámetro
sun
Type
boolean
Requis
No
Defaut
true
Description
Mostrar el Sol
Parámetro
moon
Type
boolean
Requis
No
Defaut
true
Description
Mostrar la Luna
Parámetro
mercury
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Mercurio
Parámetro
venus
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Venus
Parámetro
mars
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Marte
Parámetro
jupiter
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Júpiter
Parámetro
saturn
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Saturno
Parámetro
uranus
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Urano
Parámetro
neptune
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Neptuno
Parámetro
pluto
Type
boolean
Requis
No
Defaut
true
Description
Mostrar Plutón
Parámetro
north_node
Type
boolean
Requis
No
Defaut
true
Description
Mostrar el nodo norte
Parámetro
south_node
Type
boolean
Requis
No
Defaut
false
Description
Mostrar el nodo sur
Parámetro
chiron
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Chiron
Parámetro
lilith
Type
boolean
Requis
No
Defaut
false
Description
Mostrar la Luna Negra media (preferida; alias: mean_lilith)
Parámetro
true_lilith
Type
boolean
Requis
No
Defaut
false
Description
Mostrar la Luna Negra verdadera (osculante)
Parámetro
eris
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Eris
Parámetro
eros
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Eros
Parámetro
ceres
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Ceres
Parámetro
pallas
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Pallas
Parámetro
juno
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Juno
Parámetro
vesta
Type
boolean
Requis
No
Defaut
false
Description
Mostrar Vesta
Parámetro
asc
Type
boolean
Requis
No
Defaut
true
Description
Mostrar el Ascendente
Parámetro
ic
Type
boolean
Requis
No
Defaut
false
Description
Mostrar el IC
Parámetro
dsc
Type
boolean
Requis
No
Defaut
false
Description
Mostrar el Descendente
Parámetro
mc
Type
boolean
Requis
No
Defaut
true
Description
Mostrar el MC
Parámetro
part_of_fortune
Type
boolean
Requis
No
Defaut
false
Description
Mostrar la Parte de la Fortuna (lote árabe)

Configuración de carta (objeto chart_config)

Ajusta con precisión la apariencia visual de la carta:

Parámetro
sign_ring_thickness_fraction
Type
float
Requis
No
Defaut
0.16
Description
Grosor del anillo de signos (0.0-1.0)
Parámetro
house_ring_thickness_fraction
Type
float
Requis
No
Defaut
0.05
Description
Grosor del anillo de casas (0.0-1.0)
Parámetro
center_disk_fraction
Type
float
Requis
No
Defaut
0.45
Description
Radio del disco central (0.0-1.0)
Parámetro
planet_symbol_scale
Type
float
Requis
No
Defaut
0.35
Description
Multiplicador de tamaño de símbolos planetarios
Parámetro
planet_spacing_scale
Type
float
Requis
No
Defaut
auto
Description
Multiplicador aplicado al espaciado angular de glifos planetarios. Si se omite, el espaciado aumenta automáticamente cuando planet_symbol_scale supera el valor por defecto.
Parámetro
sign_symbol_scale
Type
float
Requis
No
Defaut
0.6
Description
Multiplicador de tamaño de símbolos de signos
Parámetro
house_number_scale
Type
float
Requis
No
Defaut
0.35
Description
Multiplicador de tamaño de números de casas
Parámetro
chart_background
Type
string
Requis
No
Defaut
null
Description
Sobrescritura de color de fondo (hex)
Parámetro
aspect_circle_background
Type
string
Requis
No
Defaut
null
Description
Color de relleno del círculo/disco central de aspectos. Por defecto, usa chart_background o el fondo del tema activo.
Parámetro
custom_planet_color
Type
string
Requis
No
Defaut
null
Description
Reemplaza todos los colores de planetas (hex)
Parámetro
custom_sign_color
Type
string
Requis
No
Defaut
null
Description
Reemplaza todos los colores de símbolos de signos (hex)
Parámetro
custom_house_color
Type
string
Requis
No
Defaut
null
Description
Reemplaza todos los colores de números de casas (hex)
Parámetro
degree_label_color
Type
string
Requis
No
Defaut
null
Description
Reemplaza el color del texto de etiquetas grado/minuto de planetas (hex o color CSS)
Parámetro
angle_label_color
Type
string
Requis
No
Defaut
null
Description
Color de respaldo para todas las etiquetas de glifos ASC/DSC/MC/IC.
Parámetro
asc_label_color
Type
string
Requis
No
Defaut
null
Description
Color de la etiqueta de glifo ASC. También disponible para dsc_label_color, mc_label_color e ic_label_color.
Parámetro
angle_label_scale
Type
float
Requis
No
Defaut
null
Description
Multiplicador de escala de respaldo para todas las etiquetas de glifos ASC/DSC/MC/IC.
Parámetro
asc_label_scale
Type
float
Requis
No
Defaut
null
Description
Multiplicador de escala de la etiqueta de glifo ASC. También disponible para dsc_label_scale, mc_label_scale e ic_label_scale.
Parámetro
angle_marker_style
Type
string
Requis
No
Defaut
glyph
Description
Renderizado de marcadores de ángulos: "glyph" conserva los glifos de abreviatura ASC/DSC/MC/IC; "french_arrow" dibuja flechas de ejes ASC/MC de estilo francés fuera del anillo de signos.
Parámetro
angle_line_span
Type
string
Requis
No
Defaut
wheel
Description
Alcance de las líneas de ejes angulares: "wheel" conserva las líneas ASC/DSC y MC/IC dentro de la zona de rueda por defecto; "full" extiende esos ejes sobre la carta y se detiene en el borde del anillo de signos. Usa angle_marker_style "french_arrow" para flechas ASC/MC fuera del anillo.
Parámetro
show_angle_labels_with_french_arrows
Type
boolean
Requis
No
Defaut
true
Description
Cuando angle_marker_style vale "french_arrow", renderiza las etiquetas de glifos ASC/DSC/MC/IC activas. Define false para ocultarlas.
Parámetro
planet_connector_clearance
Type
float
Requis
No
Defaut
auto
Description
Distancia en píxeles SVG desde el centro de un glifo de planeta/punto donde se detiene su línea conectora. Auméntala cuando glifos grandes necesiten más espacio.
Parámetro
custom_sign_bg_color
Type
string
Requis
No
Defaut
null
Description
Color hex único aplicado a los fondos de los 12 anillos de signos. Cuando se define, los fondos de signos se activan automáticamente.
Parámetro
custom_house_bg_color
Type
string
Requis
No
Defaut
null
Description
Color hex único aplicado a los fondos de los 12 anillos de casas. Cuando se define, los fondos de casas se activan automáticamente.
Parámetro
show_aspect_symbols
Type
boolean
Requis
No
Defaut
auto
Description
Muestra los glifos de aspectos en el midpoint y líneas de aspectos separadas alrededor de ellos. Activo por defecto en estilo francés e inactivo en otros estilos.
Parámetro
show_pattern_overlays
Type
boolean
Requis
No
Defaut
false
Description
Superpone estructuras y configuraciones detectadas sobre el SVG. Las estructuras admitidas incluyen grand_trine, t_square, yod, kite, grand_cross, minor_grand_trine, wedge, mystic_rectangle, cradle, castle, grand_sextile y stellium.
Parámetro
pattern_overlay_types
Type
array
Requis
No
Defaut
null
Description
Lista opcional de tipos de superposición a renderizar, por ejemplo ["grand_trine", "t_square", "stellium"]. Si se omite, todas las superposiciones detectadas admitidas pueden renderizarse hasta pattern_overlay_max_items.
Parámetro
pattern_overlay_style
Type
string
Requis
No
Defaut
subtle
Description
Intensidad de la superposición: "subtle" o "strong".
Parámetro
pattern_overlay_labels
Type
boolean
Requis
No
Defaut
false
Description
Muestra etiquetas compactas para las superposiciones de configuración renderizadas.
Parámetro
pattern_overlay_max_items
Type
integer
Requis
No
Defaut
4
Description
Número máximo de superposiciones de configuración que se dibujan. Los resaltados de signo/casa de stellium se separan y no cuentan en este límite.
Parámetro
embed_pattern_metadata
Type
boolean
Requis
No
Defaut
false
Description
Integra los datos de superposición detectados en un elemento de metadatos SVG para hover, leyenda o interfaz de selección posterior.
Parámetro
show_horoscope_shape
Type
boolean
Requis
No
Defaut
false
Description
Detecta la forma de distribución de la carta con solo los 10 planetas y la renderiza en el disco central de aspectos. Cuando se detecta una forma, las líneas/ticks centrales de aspectos se ocultan para mejorar la legibilidad.
Parámetro
horoscope_shape_style
Type
string
Requis
No
Defaut
subtle
Description
Intensidad de la superposición de forma de horóscopo: "subtle" o "strong".
Parámetro
horoscope_shape_color
Type
string
Requis
No
Defaut
#D97706
Description
Color SVG usado para todas las superposiciones de forma de horóscopo.
Parámetro
horoscope_shape_label
Type
boolean
Requis
No
Defaut
true
Description
Muestra una etiqueta compacta para la forma detectada, como Bucket, Bowl, Locomotive, Bundle, Splash o Seesaw.
Parámetro
embed_horoscope_shape_metadata
Type
boolean
Requis
No
Defaut
true
Description
Integra los datos de forma de horóscopo detectada en un elemento de metadatos SVG.
Parámetro
show_retrograde_markers
Type
boolean
Requis
No
Defaut
false
Description
Activa los marcadores retrógrados en las etiquetas de grados de planetas.
Parámetro
retrograde_marker_style
Type
string
Requis
No
Defaut
R
Description
Estilo de marcador retrógrado cuando la opción está activa: "R" o "rx" (℞).
Parámetro
degree_label_format
Type
string
Requis
No
Defaut
null
Description
Formato de etiquetas de grados de planetas: "degree" para grados enteros, "decimal" para grados decimales, o "minutes" para etiquetas apiladas de minuto + glifo de signo + grado entero. Si se omite, degree_label_precision > 0 conserva el layout anterior en minutos.
Parámetro
degree_label_precision
Type
integer
Requis
No
Defaut
0
Description
Número de decimales para degree_label_format="decimal". Rango permitido: 0-4. Para compatibilidad ascendente, si degree_label_format se omite, los valores superiores a 0 activan el layout apilado en minutos.
Parámetro
degree_label_scale
Type
float
Requis
No
Defaut
0.6
Description
Escala base del texto de etiquetas de grados de planetas.
Parámetro
degree_label_degree_scale
Type
float
Requis
No
Defaut
1.0
Description
Escala del texto de grados enteros de etiquetas precisas, relativa a degree_label_scale.
Parámetro
degree_label_minute_scale
Type
float
Requis
No
Defaut
1.0
Description
Escala del texto de minutos de etiquetas precisas, relativa a degree_label_scale.
Parámetro
degree_label_sign_scale
Type
float
Requis
No
Defaut
1.25
Description
Escala del glifo de signo zodiacal de etiquetas precisas, relativa a degree_label_scale.
Parámetro
degree_label_row_gap
Type
float
Requis
No
Defaut
1.55
Description
Espaciado de etiquetas precisas entre líneas de grado, signo y minuto, relativo a degree_label_scale.
Parámetro
houses_inside_planets
Type
boolean
Requis
No
Defaut
true
Description
Coloca las casas dentro del anillo de planetas
Parámetro
french_style
Type
boolean
Requis
No
Defaut
false
Description
Layout de horóscopo francés solo para natal: disco de aspectos dentro del borde de los signos, casas fuera de los signos y planetas fuera de las casas.
Parámetro
french_planet_radius_offset
Type
float
Requis
No
Defaut
0
Description
Modo francés solo natal. Mueve los glifos planetarios radialmente hacia fuera o hacia dentro sin mover los anillos de casas/signos.

Ejemplos de formato de etiquetas de grados

Usa degree_label_format: "minutes" para renderizar cada etiqueta precisa en líneas separadas para grado, glifo de signo y minutos. Los ejemplos siguientes son salidas PNG generadas por el mismo endpoint en layouts estándar y francés.

Carta natal estándar en PNG usando degree_label_format minutes

Layout estándar

Las casas permanecen dentro de la banda de planetas; las etiquetas precisas se apilan hacia el centro de la carta.

{
  "format": "png",
  "theme_type": "light",
  "chart_config": {
    "degree_label_format": "minutes",
    "degree_label_color": "#000000",
    "houses_inside_planets": true
  }
}
Carta natal de estilo francés en PNG usando degree_label_format minutes

Layout francés

El modo francés mantiene las etiquetas precisas, excepto las de ángulos, fuera de los glifos planetarios; las etiquetas de ángulos permanecen compactas.

{
  "format": "png",
  "theme_type": "light",
  "chart_config": {
    "degree_label_format": "minutes",
    "degree_label_color": "#000000",
    "french_style": true,
    "houses_inside_planets": false
  }
}

Ejemplos de código

curl -X POST "https://api.freeastroapi.com/api/v1/natal/chart/" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "name": "John Doe",
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "time_known": false,
    "lat": 40.7128,
    "lng": -74.006,
    "tz_str": "AUTO",
    "house_system": "placidus",
    "zodiac_type": "tropical",
    "format": "svg",
    "size": 800,
    "theme_type": "light",
    "png_quality_scale": 2.0,
    "show_metadata": true,
    "display_settings": {
        "chiron": true,
        "lilith": true,
        "north_node": true
    },
    "chart_config": {
        "sign_ring_thickness_fraction": 0.16,
        "house_ring_thickness_fraction": 0.05,
        "planet_symbol_scale": 0.35,
        "sign_symbol_scale": 0.6,
        "angle_marker_style": "glyph",
        "angle_line_span": "wheel",
        "french_style": false,
        "french_planet_radius_offset": 0,
        "show_aspect_symbols": true,
        "show_retrograde_markers": true,
        "retrograde_marker_style": "R",
        "degree_label_format": "minutes",
        "custom_planet_color": "#FF5733",
        "aspect_circle_background": "#F8F2FF",
        "show_color_background": false
    }
}' --output chart.svg

Estilo avanzado

El objeto chart_config admite control granular de grosores de línea, colores y estilos de aspectos. Los parámetros adicionales incluyen:

  • sign_line_width, sign_line_color
  • house_line_width, house_line_color
  • asc_line_width, asc_line_color (et dsc, mc, ic)
  • asc_label_color, asc_label_scale (et dsc, mc, ic)
  • angle_marker_style definido como french_arrow para flechas de ejes ASC/MC de estilo francés; las etiquetas de ángulos activos siguen visibles salvo que show_angle_labels_with_french_arrows sea false
  • angle_line_span definido como full para extender los ejes ASC/DSC y MC/IC hasta el borde del anillo de signos; usa angle_marker_style french_arrow para flechas fuera del anillo
  • planet_connector_clearance para detener las líneas de conexión antes de glifos sobredimensionados
  • aspect_circle_background para colorear solo el disco central de aspectos
  • aspect_conjunction_width, aspect_conjunction_color
  • aspect_opposition_width, aspect_trine_width, etc.

FAQ

¿Admiten estrellas fijas?

Sí. El endpoint de cartas SVG puede renderizar las estrellas fijas admitidas en la misma rueda de cuerpos que los planetas y puntos. Usa fixed_stars con ids de packs como royal_4 o behenian_20, nombres exactos de estrellas fijas, o all para el conjunto completo por defecto.

¿Qué packs de estrellas fijas están disponibles?

Hay dos packs listos para usar: behenian_20 para las 20 estrellas clásicas o behenianas, y royal_4 para Regulus, Aldebaran, Antares y Fomalhaut.

¿Puedo seleccionar estrellas fijas individuales?

Sí. Pasa los nombres exactos admitidos en el array fixed_stars, por ejemplo Spica o Regulus. El mismo array fixed_stars también acepta ids de packs como royal_4 y behenian_20.

¿Las estrellas fijas pueden mostrar aspectos?

Sí, pero los aspectos de estrellas fijas son opcionales. Activa chart_config.show_fixed_star_aspects y luego elige fixed_star_aspect_types y fixed_star_aspect_orb cuando necesites más que el flujo por defecto de conjunciones cerradas.

¿Puedo personalizar el color de las estrellas fijas?

Sí. Define chart_config.fixed_star_color con un color CSS o un valor hex. Ese color se usa para etiquetas de estrellas fijas, conectores y líneas de aspectos de estrellas fijas activadas.

¿Las estrellas fijas muestran grados y etiquetas de signo?

Sí. Las estrellas fijas usan el mismo comportamiento de colocación que otros cuerpos renderizados y pueden mostrar grado, signo y minutos cuando la configuración de etiquetas de grados lo solicita.

¿Tienen una herramienta para personalizar las cartas?

Sí. Chart Designer permite configurar colores, etiquetas, grosores de línea, temas y otras opciones visuales antes de copiar la configuración de solicitud en la API.

Abrir Chart Designer

¿Puedo personalizar colores, etiquetas, aspectos y layout?

Sí. Usa chart_config para colores, fondos, geometría de anillos, escala de glifos, estilo de conectores, colores de aspectos, grosores de línea, etiquetas de grados, marcadores retrógrados, layout de estilo francés y superposiciones de configuraciones.

¿Puedo exportar en PNG además de SVG?

Sí. Define format como svg para salida vectorial o png para salida raster. Para PNG, png_quality_scale controla el multiplicador de resolución de salida.

¿Puedo integrar el SVG en mi aplicación?

Sí. La respuesta SVG puede integrarse directamente en tu front-end, almacenarse como recurso o convertirse en tu propia cadena de renderizado. Usa la respuesta API según las reglas de caché y seguridad de tu aplicación.

¿Puedo construir una app móvil con cartas visuales gracias a esta API?

Sí. Puedes usar este endpoint para generar visuales de cartas en SVG o PNG para una aplicación móvil y luego mostrar el recurso devuelto en tu UI nativa o multiplataforma. AstroLingo es un ejemplo de aplicación construida con las capacidades de cartas visuales de FreeAstroAPI.

Ver el ejemplo AstroLingo

¿Puedo ocultar o mostrar planetas, puntos y casas?

Sí. Usa display_settings para activar u ocultar planetas, nodos, Lilith, Chiron, asteroides, ángulos y otros puntos admitidos. Cuando time_known es false, casas y ángulos se omiten automáticamente.

¿Puedo mostrar las retrogradaciones?

Sí. Define chart_config.show_retrograde_markers como true. También puedes elegir el estilo del marcador con chart_config.retrograde_marker_style, usando R o rx.

¿Puedo usar este endpoint para cartas con hora de nacimiento desconocida?

Sí. Define time_known como false. La carta sigue mostrando posiciones planetarias, pero se omiten casas y ángulos porque dependen de la hora de nacimiento.

¿Admiten configuraciones de aspectos o superposiciones de forma de horóscopo?

Sí. chart_config.show_pattern_overlays renderiza las estructuras de aspectos detectadas, y chart_config.show_horoscope_shape renderiza la forma de distribución de la carta en el disco central.

¿El renderizado de estrellas fijas es más lento?

Las estrellas fijas solo se calculan y renderizan cuando se solicitan. Usa un token de pack como royal_4 o una lista corta fixed_stars para mantener la carta legible y limitar el coste adicional de renderizado.

¿Cómo autenticar las solicitudes?

Envía tu clave API en el encabezado x-api-key con Content-Type definido como application/json.

Leer la documentación de autenticación

¿Dónde están los SVG de tránsito, sinastría o compuesto?

Usa los endpoints SVG dedicados a esos tipos de carta. Están documentados por separado del endpoint natal de cartas SVG.

Docs SVG de tránsitosDocs SVG de sinastríaDocs SVG compuesto

Endpoints relacionados

Carta natal (JSON)

Obtener los datos de la carta en formato JSON

Tránsitos

Comparar el cielo actual con la carta natal