EARTHSUN_DISTANCE

This function computes the Earth-sun distance for one or more timestamps using the NREL SPA model.

The result is returned in astronomical units (AU) and is commonly used to scale extraterrestrial irradiance in clear-sky and transposition calculations.

A common relation is:

E_{0n} = E_{sc}\left(\frac{1}{d^2}\right)

where E_{0n} is extraterrestrial normal irradiance, E_{sc} is the solar constant, and d is Earth-sun distance in AU.

Excel Usage

=EARTHSUN_DISTANCE(times, delta_t)

times (list[list], required): Timestamps for the distance calculation (ISO8601 format).
delta_t (float, optional, default: 67): Difference between terrestrial time and UT1 (seconds).

Returns (list[list]): 2D list of distances (AU), or an error string.

Example 1: Earth-Sun distance at winter solstice

Inputs:

times	delta_t
2024-12-21T12:00:00Z	67

Excel formula:

=EARTHSUN_DISTANCE({"2024-12-21T12:00:00Z"}, 67)

Expected output:

0.983724

Example 2: Earth-Sun distance near perihelion

Inputs:

times	delta_t
2024-01-03T12:00:00Z	67

Excel formula:

=EARTHSUN_DISTANCE({"2024-01-03T12:00:00Z"}, 67)

Expected output:

0.983307

Example 3: Earth-Sun distance near aphelion

Inputs:

times	delta_t
2024-07-04T12:00:00Z	67

Excel formula:

=EARTHSUN_DISTANCE({"2024-07-04T12:00:00Z"}, 67)

Expected output:

1.01672

Example 4: Scalar timestamp input

Inputs:

times	delta_t
2024-03-20T12:00:00Z	67

Excel formula:

=EARTHSUN_DISTANCE("2024-03-20T12:00:00Z", 67)

Expected output:

0.995965

Python Code

Show Code

import pandas as pd
from pvlib.solarposition import nrel_earthsun_distance as result_func

def earthsun_distance(times, delta_t=67):
    """
    Calculate the Earth-Sun distance in AU using the NREL SPA algorithm.

    See: https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.solarposition.nrel_earthsun_distance.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        times (list[list]): Timestamps for the distance calculation (ISO8601 format).
        delta_t (float, optional): Difference between terrestrial time and UT1 (seconds). Default is 67.

    Returns:
        list[list]: 2D list of distances (AU), or an error string.
    """
    try:
        def flatten_str(data):
            if not isinstance(data, list): return [str(data)]
            return [str(val) for row in data for val in (row if isinstance(row, list) else [row]) if val != ""]

        time_list = flatten_str(times)
        if len(time_list) == 0:
            return "Error: times array cannot be empty"

        dt = float(delta_t) if delta_t is not None else 67.0
        idx = pd.DatetimeIndex(time_list)

        res = result_func(
            time=idx,
            delta_t=dt
        )

        return [[float(v)] for v in res]
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

times *

Timestamps for the distance calculation (ISO8601 format).

delta_t

Difference between terrestrial time and UT1 (seconds).