lib_ephemeris █ PLANETARY EPHEMERIS MASTER LIBRARY
Unified API for calculating planetary positions. Import this single library to access all 11 celestial bodies: Sun, Moon, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Theory: VSOP87 (planets), ELP2000-82 (Moon), Meeus (Pluto)
═══════════════════════════════════════════════════════════════
█ QUICK START
//@version=6
indicator("Planetary Ephemeris Demo")
import BlueprintResearch/lib_ephemeris/1 as eph
// Get all planets
sun = eph.string_to_planet("Sun")
moon = eph.string_to_planet("Moon")
mercury = eph.string_to_planet("Mercury")
venus = eph.string_to_planet("Venus")
mars = eph.string_to_planet("Mars")
jupiter = eph.string_to_planet("Jupiter")
saturn = eph.string_to_planet("Saturn")
uranus = eph.string_to_planet("Uranus")
neptune = eph.string_to_planet("Neptune")
pluto = eph.string_to_planet("Pluto")
// Get longitude for each planet (geocentric)
sun_lon = eph.get_longitude(sun, time, true)
moon_lon = eph.get_longitude(moon, time, true)
mercury_lon = eph.get_longitude(mercury, time, true)
venus_lon = eph.get_longitude(venus, time, true)
mars_lon = eph.get_longitude(mars, time, true)
jupiter_lon = eph.get_longitude(jupiter, time, true)
saturn_lon = eph.get_longitude(saturn, time, true)
uranus_lon = eph.get_longitude(uranus, time, true)
neptune_lon = eph.get_longitude(neptune, time, true)
pluto_lon = eph.get_longitude(pluto, time, true)
// Plot all planets
plot(sun_lon, "Sun", color.yellow)
plot(moon_lon, "Moon", color.silver)
plot(mercury_lon, "Mercury", color.orange)
plot(venus_lon, "Venus", color.green)
plot(mars_lon, "Mars", color.red)
plot(jupiter_lon, "Jupiter", color.purple)
plot(saturn_lon, "Saturn", color.olive)
plot(uranus_lon, "Uranus", color.aqua)
plot(neptune_lon, "Neptune", color.blue)
plot(pluto_lon, "Pluto", color.gray)
═══════════════════════════════════════════════════════════════
█ AVAILABLE FUNCTIONS
Core Data Access:
• string_to_planet(string) → Planet enum
• get_longitude(Planet, time, preferGeo) → degrees [0, 360)
• get_declination(Planet, time) → degrees
• get_speed(Planet, time) → degrees/day
• is_retrograde(Planet, time) → true/false
Planetary Averages:
• get_avg6_geo_lon(time) → 6 outer planets average
• get_avg6_helio_lon(time)
• get_avg8_geo_lon(time) → 8 classical planets average
• get_avg8_helio_lon(time)
Utility:
• normalizeLongitude(lon) → normalize to [0, 360)
═══════════════════════════════════════════════════════════════
█ SUPPORTED PLANET STRINGS
Works with symbols or plain names (case-insensitive):
• "☉︎ Sun" or "Sun"
• "☽︎ Moon" or "Moon"
• "☿ Mercury" or "Mercury"
• "♀ Venus" or "Venus"
• "🜨 Earth" or "Earth"
• "♂ Mars" or "Mars"
• "♃ Jupiter" or "Jupiter"
• "♄ Saturn" or "Saturn"
• "⛢ Uranus" or "Uranus"
• "♆ Neptune" or "Neptune"
• "♇ Pluto" or "Pluto"
═══════════════════════════════════════════════════════════════
█ COORDINATE SYSTEMS
Geocentric: Positions relative to Earth (default for Sun/Moon)
Heliocentric: Positions relative to the Sun
Use the preferGeo parameter in get_longitude():
• true = geocentric
• false = heliocentric
Sun and Moon always return geocentric (heliocentric not applicable).
═══════════════════════════════════════════════════════════════
█ FUTURE PROJECTIONS
Project planetary positions into the future using polylines:
import BlueprintResearch/lib_vsop_core/1 as core
// Get future timestamp (250 bars ahead)
future_time = core.get_future_time(time, 250)
// Calculate future position
future_lon = eph.get_longitude(mars, future_time, true)
Use with polyline.new() to draw projected paths on your chart. See the commented showcase code in this library's source for a complete 250-bar projection example.
═══════════════════════════════════════════════════════════════
█ OPEN SOURCE
This library is part of an open-source planetary ephemeris project.
Free to use with attribution. MIT License.
═══════════════════════════════════════════════════════════════
█ REFERENCES
• Meeus, Jean. "Astronomical Algorithms" (2nd Ed., 1998)
• Bretagnon & Francou. "VSOP87 Solutions" (1988)
• Chapront-Touzé & Chapront. "ELP2000-82" (1983)
═══════════════════════════════════════════════════════════════
© 2025 BlueprintResearch (Javonnii) • MIT License
@version=6
normalizeLongitude(lon)
Normalizes any longitude value to the range [0, 360) degrees.
Parameters:
lon (float) : (float) Longitude in degrees (can be any value, including negative or >360).
Returns: (float) Normalized longitude in range [0, 360).
string_to_planet(planetStr)
Converts a planet string identifier to Planet enum value.
Parameters:
planetStr (string) : (string) Planet name (case-insensitive). Supports formats: "Sun", "☉︎ Sun", "sun", "SUN"
Returns: (Planet) Corresponding Planet enum. Returns Planet.Sun if string not recognized.
@note Supported planet strings: Sun, Moon, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
get_longitude(p, t, preferGeo)
Returns planetary longitude with automatic coordinate system selection.
Parameters:
p (series Planet) : (Planet) Planet to query.
t (float) : (float) Unix timestamp in milliseconds (use built-in 'time' variable).
preferGeo (bool) : (bool) If true, return geocentric; if false, return heliocentric.
Returns: (float) Longitude in degrees, normalized to range [0, 360).
@note Sun and Moon always return geocentric regardless of preference (heliocentric not applicable).
get_declination(p, t)
Returns planetary geocentric equatorial declination.
Parameters:
p (series Planet) : (Planet) Planet to query.
t (float) : (float) Unix timestamp in milliseconds (use built-in 'time' variable).
Returns: (float) Geocentric declination in degrees, range where positive is north.
@note Declination is always geocentric (no heliocentric equivalent in library).
get_speed(p, t)
Returns planetary geocentric longitude speed (rate of change).
Parameters:
p (series Planet) : (Planet) Planet to query.
t (float) : (float) Unix timestamp in milliseconds (use built-in 'time' variable).
Returns: (float) Geocentric longitude speed in degrees per day. Negative values indicate retrograde motion. Returns na for Moon.
@note Speed is always geocentric (no heliocentric equivalent in library). Moon speed calculation not implemented.
get_avg6_geo_lon(t)
get_avg6_geo_lon
@description Returns the arithmetic average of the geocentric longitudes for the six outer planets: Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average geocentric longitude of the six outer planets in degrees, range [0, 360).
get_avg6_helio_lon(t)
get_avg6_helio_lon
@description Returns the arithmetic average of the heliocentric longitudes for the six outer planets: Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average heliocentric longitude of the six outer planets in degrees, range [0, 360).
get_avg8_geo_lon(t)
get_avg8_geo_lon
@description Returns the arithmetic average of the geocentric longitudes for all eight classical planets: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average geocentric longitude of all eight classical planets in degrees, range [0, 360).
get_avg8_helio_lon(t)
get_avg8_helio_lon
@description Returns the arithmetic average of the heliocentric longitudes for all eight classical planets: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average heliocentric longitude of all eight classical planets in degrees, range [0, 360).
is_retrograde(p, t)
Returns true if the planet is currently in retrograde motion (geocentric speed < 0) == 0 = stationary.
Parameters:
p (series Planet) : The planet to check.
t (float) : Time in Unix timestamp (milliseconds).
Returns: true if the planet is in retrograde, false otherwise.
Geocentric
Planetary IngressDisplays planetary ingresses, the moments when a planet crosses from one zodiac sign into another. This indicator marks historical ingresses directly on your chart and projects upcoming ones with precise date, time, and retrograde status.
Powered by the open-source BlueprintResearch Planetary Ephemeris library , which implements truncated VSOP87 (planets) and ELP2000 (Moon) series for high-accuracy celestial calculations entirely within Pine Script.
█ FEATURES
• All 10 celestial bodies — Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto
• Geocentric or Heliocentric views — toggle between Earth-centered (standard astrology) and Sun-centered perspectives
• Retrograde indicator — shows ℞ symbol when a planet is in apparent retrograde motion (geocentric only)
• Future ingress projection — displays the following sign change as a dotted vertical line with customizable date/time and timezone
• Color-coded by zodiac sign — 12 fully customizable colors for each sign
• Per-sign visibility controls — easily show/hide specific signs
• Per-sign alerts — get notified when a planet enters selected signs
• Fully customizable labels — adjust size, colors, transparency, and placement
█ HOW TO USE
1. Select your planet from the dropdown
2. Choose Geocentric (traditional) or Heliocentric view
3. Historical ingresses appear as labels above price bars with a planet symbol and a zodiac sign
4. The next future ingress is shown as a dotted vertical line with projected date/time
5. Hover over labels for exact degree position (e.g., "0°Ari00'")
6. Set up alerts via "Alert on Ingress" settings for specific sign entries
█ LIMITATIONS & ACCURACY
This indicator uses optimized, truncated VSOP87 and ELP2000 series tailored for Pine Script performance. It delivers excellent accuracy for trading and analytical purposes, but is not intended for professional astronomical use.
Expected Ingress Timing Accuracy (Geocentric view):
• Sun, Moon, Mercury, Venus, Mars: Within hours to ±1 day
• Jupiter, Saturn: Within ±1–2 days
• Uranus, Neptune: Within ±3–7 days
• Pluto: Within ±1–2 weeks (simplified Meeus method, valid 1900–2100)
Heliocentric view: Inner and faster-moving planets match geocentric accuracy. Outer planets (especially Uranus/Neptune) may occasionally show larger variances (up to ±1 month in rare cases) due to their extremely slow motion amplifying minor truncation effects in the series.
Why outer planets vary more:
Slower planets take weeks or months to cross a single degree. Even minor positional discrepancies from truncated terms can shift ingress timing by days or weeks—most noticeable with the outermost bodies.
Recommendation: For mission-critical timing, always cross-reference with professional tools such as JPL Horizons , Swiss Ephemeris, or Astro.com.
█ ROADMAP
Accuracy improvements are an ongoing priority. The modular library design allows targeted upgrades to individual planets without breaking existing functionality.
Planned Enhancements:
• Higher-precision outer planet calculations (Uranus, Neptune)
• Improved heliocentric outer planet accuracy
• Enhanced Pluto method
• Additional series terms where beneficial
Updates will be released through the BlueprintResearch/lib_ephemeris library—follow for notifications.
█ OPEN SOURCE
This indicator is part of the fully open-source Planetary Ephemeris project. The core ephemeris library is public for study, modification, and reuse in your own scripts:
• BlueprintResearch/lib_ephemeris — Main planetary calculation engine
Licensed under MPL 2.0 — free to use and modify, with changes to the library shared back to the community.
Astro: Planetary Aspects v2.0I have updated the excellent script originally written by @BarefootJoey with additional functionality as listed below the script's original description:
@BarefootJoey:
In astrology, planetary aspects refer to the angles formed between two or more planets in a horoscope or birth chart. These angles are created by the positions of the planets in the sky and are thought to represent a particular energy or influence that can impact events on Earth.
The most common planetary aspects are the conjunction (when two planets are in the same position in the zodiac), the opposition (when two planets are direct across from each other in the zodiac), the trine (when two planets are 120 degrees apart in the zodiac), and the square (when two planets are 90 degrees apart in the zodiac).
This oscillator plots the current geocentric/heliocentric aspect for up to two planets and features a customizable precision of degree (up to +/- 15 degrees) for each aspect.
Additional functionality added in by @Yevolution:
1. Overlay the indicator plot on top of the main chart, with the indicator's scale placed on the left - I found it easier to spot price reactions at a given planetary aspect vs seeing the plot in a separate frame
2. Add options to plot a vertical bar for every occurrence of chosen aspects
The script source code has remained open and additional comments have been added by me to explain the changes where relevant.
When I get some more spare time I will add a function to enable future planetary aspect events to also be displayed on the chart to make forecasting using this data easier.
