Natal Chart Data#
/api/astro/natal/
Use this endpoint to get data to cast and analyse the natal charts in your front-end application. The access level for this endpoint is m1 (see access levels).
Request#
Method POST
| Value | Type | Required | Comment |
|---|---|---|---|
| year | int | yes | |
| month | int | yes | 1..12 |
| day | int | yes | |
| hour | int | yes | |
| minute | int | yes | |
| second | int | no | |
| tz | float | yes | Timezone (UTC offset in hours), f.e. -3.5 means minus 3hrs and 30 minutes latitutes |
| ln_d | int | yes | Longitude degrees 0..180 |
| ln_m | int | yes | Longitude minutes 0..59 |
| dir_ln | str | yes | east-west direction. Can be e or w |
| lt_d | int | yes | Latitude degrees 0..90 |
| lt_m | int | yes | Latitude minutes 0..59 |
| dir_lt | str | yes | north-south direction. Can be n or s |
| house_system | str | no | 'R' for Regiomontanus, 'P' for Placidus. Default is 'R' |
| calendar | str | no | 'G' for gregorian and 'J' for julian. Default is 'G'. The date time provided will be interpreted as a date in a given calendar. |
| time_format | str | no | 'UTCTZ' is for the modern time format with time zone relative to UTC. The 'LAT' or 'LMT is for local apparent/mean time, where time is based on sundial/wall clock and time zone offset is determined by geographical latitides. Use this parameter if you want to cast a chart from an old books, when horoscopes were written in this time format. |
| is_direction_from_revolution | bool | no | if set to true the backend returns the list of primary directions in the format of direction from the revolution chart. In that format the promittors are the degrees of zodiac circle. |
| transit | bool | no | if set to true the direction section (see below) is not included into the response |
Response#
This endpoint returns a rather long list of various data, so we will break it down into the logical blocks below.
Coordinates#
Key coords
This part presents the coordinates of celestial objects in the following form:
"planets": [
{
"name": "Sun",
"ecliptical": { "lon": 197.38, "lat": 0 },
"equatorial": { "rasc": 196.02, "dec": -6.82 },
"horizontal": { "azm": 307.96, "alt": -15.20 },
"mundane": { "rasc": 179.69, "dec": 0 },
"oasc": 226.48, // Oblique ascension
"umd": 128.03, // Upper Meridian Distance
"dsa": 59.53 // Diurnal Semiarc
}
// ... The same for other 6 planets. Mundane positions are given in
// a house system provided in the request
],
"cusps": [
{
"name": 1,
"ecliptical": { "lon": 324.72, "lat": 0 },
"equatorial": { "rasc": 327.01, "dec": -13.28 },
"horizontal": { "azm": 179.02, "alt": 6.36 },
"mundane": { "rasc": 56.00, "dec": 0 },
"oasc": 226.48,
"umd": 128.03,
"dsa": 59.53
}
// ... The same for other 2..12 cusps
],
"nodes": [
{
"name": "North Node",
"ecliptical": { "lon": 324.72, "lat": 0 },
"equatorial": { "rasc": 327.01, "dec": -13.28 },
"horizontal": { "azm": 179.02, "alt": 6.36 },
"mundane": { "rasc": 56.00, "dec": 0 },
"oasc": 226.48,
"umd": 128.03,
"dsa": 59.53
}
// ... The same for S. Node. Coordinates are given for True Nodes
],
"stars": [
{
"name": "Alcyone",
"ecliptical": { "lon": 324.72, "lat": 0 },
"equatorial": { "rasc": 327.01, "dec": -13.28 },
"horizontal": { "azm": 179.02, "alt": 6.36 },
"mundane": { "rasc": 56.00, "dec": 0 },
"oasc": 226.48,
"umd": 128.03,
"dsa": 59.53
}
// ... The same for other stars
],
"parts": [ // Only Pars of Fortune
{
"name": "Pars of Fortune",
"ecliptical": { "lon": 155.32, "lat": 0 },
"equatorial": { "rasc": 157.14, "dec": 9.55 },
"horizontal": { "azm": 347.07, "alt": -3.38 },
"mundane": { "rasc": 185.024, "dec": 0 },
"oasc": 111.64,
"umd": 166.91,
"dsa": 135.49
}
],
"mund_antis": [ // Mundane antiscia of 7 planets
{
"name": "Sun",
"closest": {
"ecliptical": { "lon": 324.72, "lat": 0 },
"equatorial": { "rasc": 327.01, "dec": -13.28 },
"horizontal": { "azm": 179.02, "alt": 6.36 },
"mundane": { "rasc": 56.00, "dec": 0 },
"oasc": 226.48,
"umd": 128.03,
"dsa": 59.53
},
"farest": {...}
}
// ... The same for other 6 planets
],
"aspects": { // coordinates of major aspects of each planet
"Sun": [
{
"name": -120,
"ecliptical": { "lon": 324.72, "lat": 0 },
"equatorial": { "rasc": 327.01, "dec": -13.28 },
"horizontal": { "azm": 179.02, "alt": 6.36 },
"mundane": { "rasc": 56.00, "dec": 0 },
"oasc": 226.48,
"umd": 128.03,
"dsa": 59.53
}
// The same for other major aspects: -90, -60, 0, 60, 90, 120, 180
]
// The same for other 6 planets
}
Planetary Speeds#
Key planetary_speeds
This part represents the current speeds of the planets:
[
{
"name": "Sun",
"speed": {
"in_lon": 1.0058326303364813,
"in_lat": -0.000024446217625552297,
"percent": 102.0480870229323, // Deviation from the average speed in longitude
"rate": "Average", // Can be Fast, or Slow
"direction": "D" // D-direct, R-Retrograde, S-Stationary
}
},
// The same for other 6 planets
]
Positions in a House#
Key pos_in_house
This part presents the position of planets and Pars of Fortune in astrological houses in the following form:
/**
* position of a planet in a specific house,
* and distances from adjacent cusps on ecliptic.
*/
"ecliptical": [
{
"name": "Sun",
"in_house": 6, // House numbers are 1..12
"from_cusp": 50.65, // degrees
"to_next_cusp": 106.73
}
// The same for other 6 planets and PoF
],
/**
* position of a planet or PoF in a specific spacial area
* between house dividers, and distances to the house
* dividers, measured along a declination circle of
* a planet. It can be null in extreme latitudes
* in Placidus house system, if planet falls into
* the area of never ascending point, where the
* Placidus system doesn't exists.
*/
"mundane": [
{
"name": "Sun",
"in_house": 6, // House numbers are 1..12
"from_cusp": 50.65, // degrees
"to_next_cusp": 106.73
}
// The same for other 6 planets and PoF
]
Screen Display Positions#
Key on_screen
This part represents the data for displaying cusps and planets on the chart. For example, the ASC has an angle of 0 degrees on the screen, the 7th house is displayed in 180 degrees.
There are two display styles for the cusp and planets. The modern style assumes that the cusps are drawn with their actual widths. For example, if the distance between the ASC and the 2nd house cusp is 58 degrees, then the 2nd house should be displayed at 58 degrees on the chart's circle.
In the traditional style, houses are displayed equal. Accordingly, the displayed positions of the planets in the houses is adjusted.
Because plant glyphs can intersect each other, this endpoint returns two kinds of angles - the planet's true center and its corrected position.
"modern_style": {
"cusps": [
{
"name": 11,
"angle": 159.35
}
// The same for other houses
],
"in_circle": [
{
"name": "Venus",
"angle_of_center": 229.45,
"angle_corrected": 229.24
}
// The same for other planets, True Nodes and Pars of Fortune
]
},
"trad_style": {
"cusps": [
{
"name": 2,
"angle": 60.0
}
// The same for other houses
],
"in_circle": [
{
"name": "Venus",
"angle_of_center": 219.05,
"angle_corrected": 217.78
}
// The same for other planets and Pars of Fortune
]
},
"on_ruler": [ // if you display a ruler with planets beneath the chart
{
"name": "Jupiter",
"x_center": 1.87,
"x_corrected": 1.87
}
// The same for other planets
]
Primary Direction#
Key directions
This part represents the list of primary directions of all possible promittors to significators. Significators can be
- The cusps (int:
1..12) - The planets (str:
Sun``,Moon``, ...) - Pars of Fortune (str:
Pars of Fortune)
Promittors are:
- Planets, their aspects and antiscia,
- Royal Stars
It has the following form:
[
{
"significator": "Pars of Fortune",
"promittor_name": "Moon",
"promittor_type": "antis",
"promittor_ray_name": "farest", // The promitter is the fartest antiscia of the Moon
"direction_type": "C", // Converse or Direct
"arc": 0.07984307374766786,
"age": 0.08100523404332836
},
{
"significator": 1, // Means the 1st house cusp, i.e. the ASC
"promittor_name": "Jupiter",
"promittor_type": "aspect",
"promittor_ray_name": -120, // Means the promittor is the dexter trigon of Jupiter
"direction_type": "C",
"arc": 0.22525548696020792,
"age": 0.22853420571485097
},
{
"significator": 2, // The 2nd house cusp
"promittor_name": "Mintaka",
"promittor_type": "star",
"promittor_ray_name": 0, // the body of the star Mintaka
"direction_type": "D",
"arc": 0.2612915457968228,
"age": 0.26509478940786546
}
// Similar data is for the rest of promittors and significators
]
Primary Directions From Revolution#
if the flag is_direction_from_revolution in request is set to true you'll get the list of primary directions, where promittors are the zodiac degrees, and the significators are the ASC, MC and 7 planets:
[
{
"significator": 1, // ASC
"promittors": [
{
"zodiac_degree": 204,
"arc": 0.05908122268553484
},
{
"zodiac_degree": 205,
"arc": 1.5737905106353764
},
// ... the same for other 358 degrees
],
},
{
"significator": 10, // MC
"promittors": [...]
},
{
"significator": "Sun",
"promittors": [...]
},
{
"significator": "Moon",
"promittors": [...]
}
// The same for other planets
]
This is the responsibility of the backend application to transfer the arc into days of life. Here is the hint how to do that
- Take the period of revolution (see Revolutions of Planets)
- Divide this period on 360 and multiply on the arc. Example, for the Solar return the arc of 45 means 365 / 365.24 * 45 (days of life).
Receptions#
Key receptions
This part represents receptions of the planets. It uses Motinus table of receptions:
[
{
"name": "Sun",
"by_rulership": "Venus",
"by_exaltation": "Saturn",
"by_triplicity": {
"day": "Saturn",
"night": "Venus",
"common": "Mercury"
},
"by_fall": "Sun",
"by_detriment": "Mars"
}
// Tha same for other 6 planets
]
Close Aspects#
Key close_aspects
This section contains information about the close aspects of the planets. If there are no close aspects between the planets, they are not displayed in this list.
[
{
"planet1": "Sun",
"planet2": "Moon",
"orb1": 18, // in degrees
"orb2": 12,
"aspect": 120, // in degrees
"distance": 3.44, // distance in aspect in degrees
"is_applying": false,
"type": "Complete platic", // meand the distance is less then 12 degree orb
"effect": "80%" // (max_orb - distance) relative to distance
}
// the same for other apecting planets
]
Close Aspects Cusps#
Key close_aspects_cusps
Contains data on close aspects between planets and cusps. If there is no close aspect between the planet and the cusp, it is not displayed in the list.
[
{ // The Sun casts a close sextile to the ASC
"cusp": 1,
"planet": "Sun",
"aspect": 60,
"distance": 0.81, // Very close aspect, less than 1 degree
// The distance is just 5% of Sun's orb (which is 18 degrees)
"effect": "95%"
}
// The same for other planets and cusps
]
Conjunctions with Stars#
Key conjunction_stars
This part contains the list of conjunctions of planets and cusps with the fixed stars.
"ecliptical": [
{
"star": "Alnilam",
"planet": "Mars",
"distance": 0.79
},
{
"star": "Alphard",
"cusp": 9,
"distance": 4.48
}
// The same for other conjunctions
],
"equatorial": [
// similar list for conjunctions on equatorial plane
],
"mundane": [
// similar for mundane conjunctions alon the diarnal arcs
]