# Batch Sun Position and Daylight (`snowball_tools/batch-sun-position-daylight`) Actor

Batch sun position API: calculate solar elevation, azimuth, sunrise, sunset, solar noon and daylight for up to 1,000 coordinates and timestamps. Export JSON or CSV.

- **URL**: https://apify.com/snowball_tools/batch-sun-position-daylight.md
- **Developed by:** [Snowball Tools](https://apify.com/snowball_tools) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 calculated solar rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Batch Sun Position and Daylight

Calculate the sun's elevation and azimuth at a specified instant, plus sunrise,
sunset, solar noon and daylight duration for each coordinate/timestamp pair.
Process up to 1,000 rows in one batch without geocoding, proxies, external data
services or AI-generation calls.

Use it to add solar geometry to location datasets, prepare outdoor schedules,
compare daylight between sites, or supply an automation with structured sun data.

### Use on Apify

1. Click **Try for free** on this Actor's Store page.
2. Open **Input**, switch to the JSON editor, and paste a batch using the example below.
3. Click **Start** and wait for the run to finish.
4. Open **Output** to view the solar position and daylight table.
5. Use the output download/export controls to save the results as JSON or CSV.

Runs use your account's available credits and the listing's current pricing.
Malformed JSON or an invalid coordinate/timestamp is rejected; the batch is
validated before any calculation results are written.

### Input

```json
{
  "locations": [
    {
      "label": "Greenwich summer noon",
      "latitude": 51.48,
      "longitude": 0,
      "datetime": "2026-06-21T12:00:00Z"
    }
  ]
}
```

- `locations`: 1 to 1,000 objects. Output preserves input order.
- `latitude`: finite decimal degrees from -90 to 90, north-positive.
- `longitude`: finite decimal degrees from -180 to 180, east-positive.
- `datetime`: an ISO timestamp including `Z` or an explicit offset such as
  `-07:00`. The instant is converted to UTC. Supported UTC years: 1900–2100.
- `label`: optional text, at most 200 characters, carried into the result.

Supply coordinates and timezone explicitly. This tool does not infer a location,
look up addresses, or detect local timezones or daylight-saving rules.

### Output

Each row contains the input coordinates and label, `datetime_utc`, geometric
`elevation_degrees`, approximate refracted `apparent_elevation_degrees`,
`azimuth_degrees` measured clockwise from north, `zenith_degrees`, solar
declination and equation of time. It also contains:

| Field | Meaning |
| --- | --- |
| `solar_day` | UTC calendar date of the input instant |
| `solar_noon_utc` | Calculated solar transit for that solar day |
| `sunrise_utc`, `sunset_utc` | Approximate horizon crossings, or null if absent |
| `daylight_minutes` | Calculated interval, 0 during polar night, 1,440 during polar day, or null near an unresolved transition |
| `daylight_state` | `normal`, `polar_day`, `polar_night`, or `transition` |
| `method`, `method_source` | Calculation method and source reference |

Daily events are the solar cycle anchored to `solar_day`; they are not a search
for all crossings occurring inside midnight-to-midnight UTC. At large east/west
longitudes, sunrise or sunset can be on an adjacent UTC calendar date. Full ISO
timestamps retain that date. At the exact geographic poles, or when azimuth is
mathematically undefined, `azimuth_degrees` is null.

### Method and limits

The calculation uses NOAA-style Meeus solar equations and a 90.833-degree zenith
for sunrise/sunset. Results are approximate and assume a level, unobstructed
horizon. Terrain, buildings, observer elevation, local weather, changing
atmospheric conditions and shadows are not modeled. The apparent elevation uses
an approximate refraction correction. High latitudes and polar transitions need
particular care. This is a planning/data utility; no survey, safety-critical or
engineering-grade accuracy is claimed.

Reference: [NOAA solar calculation details](https://gml.noaa.gov/grad/solcalc/calcdetails.html).
NOAA notes that its own calculator is no longer actively maintained. This is an
independent implementation; it makes no NOAA endorsement claim. Twilight,
golden-hour windows, solar-panel modeling and timezone lookup are not included.

### Execution and billing

The Actor reads the submitted batch and writes one dataset item per calculated
row. Dataset export provides JSON, CSV and other formats supported by Apify.
Calculations require no external data service, proxy or AI-generation call.
The live Apify Store page determines current availability and pricing.

Apify handles per-result billing through its synthetic
`apify-default-dataset-item` event, once per row written to the default dataset,
according to the listing's configured pricing. The calculation code makes no
manual charge calls and sets no selling price. Pricing, platform permissions and
publication are managed in Apify.

# Actor input Schema

## `locations` (type: `array`):

One output row per input object, in the same order. Latitude is north-positive; longitude is east-positive. Supported years after conversion to UTC are 1900 through 2100.

## Actor input object example

```json
{
  "locations": [
    {
      "label": "Greenwich summer noon",
      "latitude": 51.48,
      "longitude": 0,
      "datetime": "2026-06-21T12:00:00Z"
    }
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        {
            "label": "Greenwich summer noon",
            "latitude": 51.48,
            "longitude": 0,
            "datetime": "2026-06-21T12:00:00Z"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("snowball_tools/batch-sun-position-daylight").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "locations": [{
            "label": "Greenwich summer noon",
            "latitude": 51.48,
            "longitude": 0,
            "datetime": "2026-06-21T12:00:00Z",
        }] }

# Run the Actor and wait for it to finish
run = client.actor("snowball_tools/batch-sun-position-daylight").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    {
      "label": "Greenwich summer noon",
      "latitude": 51.48,
      "longitude": 0,
      "datetime": "2026-06-21T12:00:00Z"
    }
  ]
}' |
apify call snowball_tools/batch-sun-position-daylight --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,snowball_tools/batch-sun-position-daylight"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/s8md1g7QrgjSVghBV/builds/0EeeSz3tdK6BqcIPZ/openapi.json