Ephemeris

POST/api/v1/ephemeris/calculate

Query planetary positions for a single timestamp or a full date range with configurable steps, astrologer-grade metadata, optional aspects, and table output designed for calendars, exports, and month-by-month ephemeris views.

Full URL

https://api.freeastroapi.com/api/v1/ephemeris/calculate

A convenience GET /api/v1/ephemeris alias is also available for query-string workflows.

Monthly Grid Example

This is the clearest way to understand what table_style=grid returns: one row per day, one column per body, with formatted positions ready for a frontend calendar or export view.

Date	Weekday	Sid.t	Sun	Moon	Mercury	Venus	Mars	Jupiter	Saturn
1	Sun	10:35:16	10°24' Pis	09°07' Leo	21°58' Pis Rx	23°13' Pis	28°45' Aqu	15°15' Can Rx	01°43' Ari
2	Mon	10:39:12	11°25' Pis	22°53' Leo	21°28' Pis Rx	24°28' Pis	29°32' Aqu	15°13' Can Rx	01°51' Ari
3	Tue	10:43:09	12°25' Pis	06°25' Vir	20°50' Pis Rx	25°42' Pis	00°19' Pis	15°12' Can Rx	01°58' Ari
4	Wed	10:47:05	13°25' Pis	19°43' Vir	20°05' Pis Rx	26°57' Pis	01°06' Pis	15°10' Can Rx	02°05' Ari
5	Thu	10:51:02	14°25' Pis	02°44' Lib	19°15' Pis Rx	28°12' Pis	01°54' Pis	15°09' Can Rx	02°12' Ari
6	Fri	10:54:59	15°25' Pis	15°28' Lib	18°19' Pis Rx	29°27' Pis	02°41' Pis	15°08' Can Rx	02°20' Ari
7	Sat	10:58:55	16°25' Pis	27°56' Lib	17°20' Pis Rx	00°41' Ari	03°28' Pis	15°07' Can Rx	02°27' Ari
8	Sun	11:02:52	17°25' Pis	10°10' Sco	16°20' Pis Rx	01°56' Ari	04°16' Pis	15°06' Can Rx	02°34' Ari
9	Mon	11:06:48	18°25' Pis	22°14' Sco	15°19' Pis Rx	03°10' Ari	05°03' Pis	15°06' Can Rx	02°41' Ari
10	Tue	11:10:45	19°25' Pis	04°10' Sag	14°19' Pis Rx	04°25' Ari	05°50' Pis	15°05' Can Rx	02°49' Ari
11	Wed	11:14:41	20°25' Pis	16°03' Sag	13°22' Pis Rx	05°40' Ari	06°37' Pis	15°05' Can Rx	02°56' Ari
12	Thu	11:18:38	21°25' Pis	27°57' Sag	12°28' Pis Rx	06°54' Ari	07°25' Pis	15°05' Can	03°04' Ari
13	Fri	11:22:34	22°25' Pis	09°57' Cap	11°38' Pis Rx	08°09' Ari	08°12' Pis	15°06' Can	03°11' Ari
14	Sat	11:26:31	23°25' Pis	22°09' Cap	10°53' Pis Rx	09°23' Ari	08°59' Pis	15°06' Can	03°18' Ari
15	Sun	11:30:28	24°25' Pis	04°35' Aqu	10°14' Pis Rx	10°38' Ari	09°46' Pis	15°07' Can	03°26' Ari
16	Mon	11:34:24	25°24' Pis	17°19' Aqu	09°41' Pis Rx	11°52' Ari	10°34' Pis	15°08' Can	03°33' Ari
17	Tue	11:38:21	26°24' Pis	00°24' Pis	09°14' Pis Rx	13°06' Ari	11°21' Pis	15°09' Can	03°41' Ari
18	Wed	11:42:17	27°24' Pis	13°51' Pis	08°54' Pis Rx	14°21' Ari	12°08' Pis	15°10' Can	03°48' Ari
19	Thu	11:46:14	28°24' Pis	27°39' Pis	08°39' Pis Rx	15°35' Ari	12°55' Pis	15°11' Can	03°56' Ari
20	Fri	11:50:10	29°23' Pis	11°44' Ari	08°31' Pis Rx	16°49' Ari	13°42' Pis	15°13' Can	04°03' Ari
21	Sat	11:54:07	00°23' Ari	26°03' Ari	08°30' Pis	18°04' Ari	14°30' Pis	15°15' Can	04°10' Ari
22	Sun	11:58:03	01°23' Ari	10°30' Tau	08°34' Pis	19°18' Ari	15°17' Pis	15°17' Can	04°18' Ari
23	Mon	12:02:00	02°22' Ari	24°59' Tau	08°43' Pis	20°32' Ari	16°04' Pis	15°19' Can	04°25' Ari
24	Tue	12:05:57	03°22' Ari	09°26' Gem	08°58' Pis	21°46' Ari	16°51' Pis	15°21' Can	04°33' Ari
25	Wed	12:09:53	04°21' Ari	23°45' Gem	09°18' Pis	23°00' Ari	17°38' Pis	15°24' Can	04°40' Ari
26	Thu	12:13:50	05°21' Ari	07°55' Can	09°43' Pis	24°15' Ari	18°25' Pis	15°27' Can	04°48' Ari
27	Fri	12:17:46	06°20' Ari	21°52' Can	10°13' Pis	25°29' Ari	19°12' Pis	15°30' Can	04°55' Ari
28	Sat	12:21:43	07°19' Ari	05°36' Leo	10°47' Pis	26°43' Ari	19°59' Pis	15°33' Can	05°03' Ari
29	Sun	12:25:39	08°19' Ari	19°08' Leo	11°25' Pis	27°57' Ari	20°46' Pis	15°36' Can	05°10' Ari
30	Mon	12:29:36	09°18' Ari	02°27' Vir	12°07' Pis	29°11' Ari	21°33' Pis	15°39' Can	05°18' Ari
31	Tue	12:33:32	10°17' Ari	15°34' Vir	12°53' Pis	00°25' Tau	22°20' Pis	15°43' Can	05°25' Ari

Choose JSON

Use format=json when you want a single snapshot or a machine-friendly range response for app logic.

Choose Rows / Columns

Use table_style=rows or columns when you need larger exports, CSV-style processing, or custom UI transforms.

Choose Grid

Use table_style=grid when you want a month-style ephemeris table with weekday and sidereal time built in.

Most Common Requests

curl -X POST "https://api.freeastroapi.com/api/v1/ephemeris/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
   "start": "2026-03-01T00:00:00Z",
   "bodies": ["Sun", "Moon", "Mercury"],
   "include_moon_void_of_course": true,
   "fixed_stars": ["Spica", "Regulus"]
 }'

curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
 -H "x-api-key: YOUR_API_KEY" \
 --data-urlencode "start=2026-03-01T00:00:00Z" \
 --data-urlencode "end=2026-03-31T00:00:00Z" \
 --data-urlencode "step=1d" \
 --data-urlencode "response_mode=table" \
 --data-urlencode "table_style=grid" \
 --data-urlencode "bodies=Sun,Moon,Mercury,Venus,Mars,Jupiter,Saturn,Uranus,Neptune,Pluto,Chiron,True_Lilith"

curl -G "https://api.freeastroapi.com/api/v1/ephemeris" \
 -H "x-api-key: YOUR_API_KEY" \
 --data-urlencode "start=2026-03-14T04:00:00Z" \
 --data-urlencode "end=2026-03-14T08:00:00Z" \
 --data-urlencode "step=5m" \
 --data-urlencode "bodies=Moon,Sun"

Key parameters

Parameter	Type	Req	Description
start	string	Yes	Required ISO datetime. If only start is provided, the endpoint returns a single snapshot for that moment.
end	string	No	Optional ISO datetime for range queries. Must be greater than or equal to start.
step	string	No	Whole minute/hour/day interval such as 1m, 5m, 15m, 1h, 6h, 1d, or 7d. Default: 1d.
city	string	No	POST only. Works like natal: if provided without lat/lng, the backend resolves coordinates automatically.
lat	float	No	Latitude. If lat/lng are provided, they override city lookup and are used directly.
lng	float	No	Longitude. Required together with lat for direct coordinate requests.
tz_str	string	No	Timezone string or AUTO. AUTO uses the resolved coordinates and date to determine timezone.
bodies	array[str] \| csv	No	Requested bodies or points. Accepts a POST array or a comma-separated GET string.
format	string	No	json or table. Default: json.
response_mode	string	No	Alias for format. Useful for table requests in query-string workflows.
table_style	string	No	rows, columns, or grid. Grid is the month-style calendar output.
zodiac_type	string	No	tropical (default) or sidereal.
sidereal_ayanamsa	string	No	Used only when zodiac_type=sidereal. Matches the natal naming conventions.
house_system	string	No	House system used when houses or angles are calculated. Default: placidus.
include_aspects	boolean	No	If true, includes aspect data for each snapshot.
include_minor_aspects	boolean	No	If true, expands aspects to include minor aspect types.
include_moon_void_of_course	boolean	No	If true, adds astrology.moon_void_of_course with the current VOC state, next Moon sign ingress, and next applying major Moon aspect before ingress when one exists.
include_fixed_stars	boolean	No	If true, returns the default astrology fixed-star set under fixed_stars for each snapshot.
fixed_stars	array[str] \| csv	No	Optional explicit fixed-star list. Accepts a POST array or a comma-separated GET string, for example Spica,Regulus.
include_houses	boolean	No	If true, returns houses. Auto-enabled when coordinates are available unless explicitly set to false.
include_angles	boolean	No	If true, returns ascendant/MC/related angle data. Auto-enabled when coordinates are available unless explicitly set to false.

Location behavior

Recommended flow: use City Search, let the user pick an exact result, then send lat, lng, and ideally tz_str.
city on POST /api/v1/ephemeris/calculate is a convenience fallback. If you send only a city, the backend resolves coordinates automatically.
If you already have coordinates, send them. Do not send only the city name back after City Search unless you want the backend to do a second lookup.
When coordinates are present, houses and angles are included automatically unless you explicitly disable them.

Range limits

table_style=grid is for month-style displays and is limited to 31 rows. Larger requests return 400 grid_range_too_large.
Use 1h and 1d for standard tables and exports.
Use minute steps such as 1m or 5m only for exact timing work.
Minute-level ranges are capped at 1440 rows, roughly 24h at 1m. Larger requests return 400 minute_range_too_large.
rows and columns allow larger exports, still subject to the endpoint’s general row cap.

Moon void of course

Set include_moon_void_of_course=true to add a moon_void_of_course object under astrology for each snapshot.
The calculation uses exact major Moon aspects to the Sun, Mercury, Venus, Mars, Jupiter, and Saturn before the Moon changes sign.
For table responses, the same object is available inside each raw_rows[].astrology payload.

Supported bodies

Core bodies

Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto

Nodes and lunar points

Mean Node, True Node, Lilith, True Lilith

Asteroids and minor bodies

Chiron, Pholus, Ceres, Pallas, Juno, Vesta

Coordinate-based points

Ascendant, MC, Vertex, Part of Fortune

Coordinate-based points require lat and lng.

Response samples

{
  "meta": {
    "start": "2026-03-01T00:00:00Z",
    "end": null,
    "step": null,
    "rows": 1,
    "bodies": ["Sun", "Moon", "Mercury"],
    "format": "json",
    "zodiac_type": "tropical",
    "sidereal_ayanamsa": null,
    "timezone": "UTC"
  },
  "data": {
    "timestamp": "2026-03-01T00:00:00Z",
    "local_timestamp": "2026-03-01T00:00:00+00:00",
    "subject": {
      "datetime": "2026-03-01T00:00:00+00:00",
      "location": {
        "city": null,
        "lat": null,
        "lng": null,
        "timezone": "UTC"
      },
      "settings": {
        "julian_day": 2461100.5,
        "julian_day_tt": 2461100.5007972275,
        "delta_t_days": 0.0007972275448330983,
        "delta_t_seconds": 68.8804598735797,
        "zodiac_type": "Tropical",
        "house_system": "placidus"
      }
    },
    "bodies": {
      "Sun": {
        "id": "sun",
        "name": "Sun",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "sign_id": "pisces",
        "pos": 10.406,
        "abs_pos": 340.406,
        "retrograde": false,
        "speed": 1.0037,
        "is_stationary": false,
        "latitude_deg": 0.000076,
        "distance_au": 0.990714622,
        "position_text": "10°24' Pisces",
        "degree_in_sign": 10.406,
        "longitude_deg": 340.406,
        "motion_state": "direct"
      },
      "Moon": {
        "id": "moon",
        "name": "Moon",
        "sign": "Leo",
        "sign_abbr": "Leo",
        "sign_id": "leo",
        "pos": 9.117,
        "abs_pos": 129.117,
        "retrograde": false,
        "speed": 13.8619,
        "is_stationary": false,
        "latitude_deg": 2.635536,
        "distance_au": 0.002504401,
        "position_text": "09°07' Leo",
        "degree_in_sign": 9.117,
        "longitude_deg": 129.117,
        "declination_deg": 20.516062,
        "motion_state": "direct"
      },
      "Mercury": {
        "id": "mercury",
        "name": "Mercury",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "sign_id": "pisces",
        "pos": 21.973,
        "abs_pos": 351.973,
        "retrograde": true,
        "speed": -0.428,
        "is_stationary": false,
        "latitude_deg": 3.294498,
        "distance_au": 0.70680082,
        "position_text": "21°58' Pisces Rx",
        "degree_in_sign": 21.973,
        "longitude_deg": 351.973,
        "declination_deg": -0.156033,
        "motion_state": "retrograde"
      }
    },
    "astrology": {
      "retrograde_bodies": ["Mercury"],
      "stations": [],
      "ingresses": [
        {
          "body": "Moon",
          "sign": "Leo",
          "degree_in_sign": 9.117,
          "direction": "entering_sign"
        }
      ],
      "angular_bodies": [],
      "notable_conditions": [
        "retrograde:Mercury",
        "ingress:Moon",
        "moon_phase:waxing_gibbous"
      ],
      "moon_phase": {
        "name": "Waxing Gibbous",
        "phase_angle_deg": 148.711,
        "is_waxing": true
      },
      "moon_void_of_course": {
        "is_void": false,
        "definition": "No further exact major Moon aspect to Sun, Mercury, Venus, Mars, Jupiter, or Saturn before the Moon changes sign.",
        "current_sign": "Leo",
        "next_sign": "Virgo",
        "sign_ingress_at": "2026-03-02T12:33:41Z",
        "next_applying_aspect": {
          "body": "mars",
          "aspect": "opposition",
          "exact_at": "2026-03-02T12:27:23Z"
        }
      }
    }
  }
}

{
  "meta": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T00:00:00Z",
    "step": "1d",
    "rows": 31,
    "bodies": ["Sun", "Moon", "Mercury"],
    "format": "table",
    "table_style": "grid",
    "zodiac_type": "tropical",
    "sidereal_ayanamsa": null,
    "timezone": "UTC"
  },
  "display": {
    "sign_style": "abbr",
    "cell_format": "parts",
    "motion_markers": {
      "retrograde": "Rx",
      "stationary": "S"
    },
    "columns": ["date", "weekday", "sidereal_time", "Sun", "Moon", "Mercury"]
  },
  "rows": [
    {
      "date": { "iso": "2026-03-01", "day": 1 },
      "weekday": "Sun",
      "sidereal_time": "10:35:16",
      "Sun": {
        "text": "10°24' Pis",
        "degree_text": "10°24'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": null,
        "entered_sign": false,
        "station": false
      },
      "Mercury": {
        "text": "21°58' Pis Rx",
        "degree_text": "21°58'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": "Rx",
        "entered_sign": false,
        "station": false
      }
    },
    {
      "date": { "iso": "2026-03-02", "day": 2 },
      "weekday": "Mon",
      "sidereal_time": "10:39:12",
      "Sun": {
        "text": "11°25' Pis",
        "degree_text": "11°25'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": null,
        "entered_sign": false,
        "station": false
      },
      "Moon": {
        "text": "22°53' Leo",
        "degree_text": "22°53'",
        "sign": "Leo",
        "sign_abbr": "Leo",
        "motion_marker": null,
        "entered_sign": true,
        "station": false
      },
      "Mercury": {
        "text": "21°28' Pis Rx",
        "degree_text": "21°28'",
        "sign": "Pisces",
        "sign_abbr": "Pis",
        "motion_marker": "Rx",
        "entered_sign": false,
        "station": false
      }
    }
  ],
  "raw_rows": [
    {
      "timestamp": "2026-03-01T00:00:00Z",
      "bodies": {
        "Sun": {
          "abs_pos": 340.406,
          "degree_in_sign": 10.406,
          "declination_deg": -7.665505,
          "speed": 1.0037
        },
        "Moon": {
          "abs_pos": 129.117,
          "degree_in_sign": 9.117,
          "declination_deg": 20.516062,
          "speed": 13.8619
        },
        "Mercury": {
          "abs_pos": 351.973,
          "degree_in_sign": 21.973,
          "declination_deg": -0.156033,
          "speed": -0.428
        }
      }
    }
  ]
}

FAQ

Common questions about the Western astrology ephemeris API, monthly planetary tables, Moon void-of-course data, and supported calculation options.

What is an astrology ephemeris API?

An astrology ephemeris API returns planetary positions for a specific date and time or across a date range. This endpoint calculates tropical or sidereal zodiac positions for planets, the Moon, nodes, asteroids, angles, houses, aspects, fixed stars, and month-style ephemeris tables.

Can I get a monthly planetary ephemeris table?

Yes. Use GET /api/v1/ephemeris with format=table and table_style=grid to return one row per day and one column per requested body. Grid mode is designed for monthly astrology calendars and is limited to 31 rows per request.

Does the ephemeris endpoint support Moon void of course?

Yes. Set include_moon_void_of_course=true to add astrology.moon_void_of_course for each snapshot. The response includes whether the Moon is void, the next Moon sign ingress, and the next applying major Moon aspect before ingress when one exists.

How accurate are the planetary positions?

The backend uses precise astronomical calculations for planetary longitude, latitude, speed, retrograde state, declination, fixed stars, and house data where applicable. Results include Julian day metadata so applications can audit the calculation context.

Can I request tropical and sidereal ephemeris data?

Yes. Use zodiac_type=tropical for the default Western tropical ephemeris or zodiac_type=sidereal with sidereal_ayanamsa, such as lahiri, for sidereal calculations.

Can I include houses and angles in an ephemeris request?

Yes. Send lat and lng, or a resolvable city on POST, then enable include_houses or include_angles. When coordinates are present, houses and angles are auto-enabled unless explicitly disabled.

What time steps are supported?

The endpoint supports whole minute, hour, and day intervals such as 1m, 5m, 15m, 1h, 6h, 1d, and 7d. Minute-level ranges are capped at 1440 rows, while grid tables are capped at 31 rows.

Can I calculate aspects in the ephemeris response?

Yes. Set include_aspects=true to include snapshot aspect data. Set include_minor_aspects=true when you also need minor aspects beyond the major aspect set.

Which planets and astrology points can I request?

The endpoint supports Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, Mean Node, True Node, Lilith, True Lilith, Ascendant, MC, Vertex, and Part of Fortune.

Can I use the ephemeris API for astrology apps and calendars?

Yes. The JSON format is suited for application logic, while table rows, columns, and grid output are suited for astrology calendars, dashboards, exports, and month-by-month ephemeris displays.