# Solar Position API
> Solar-position astronomy as an API, computed locally and deterministically with the NOAA solar-calculator algorithm. The position endpoint gives the sun's elevation (altitude above the horizon), azimuth (clockwise from true north), zenith angle and hour angle for any latitude, longitude, date and local time with a UTC offset — telling you exactly where the sun is in the sky and whether it is above the horizon. The declination endpoint gives the solar declination — the sun's angle north or south of the equator, about +23.44° at the June solstice and −23.44° in December — and the equation of time, the difference between apparent and mean solar time, for any date. The solar-noon endpoint gives the local clock time of solar noon, the peak (noon) elevation 90 − |latitude − declination| and the day length, handling polar day and polar night. Latitudes and longitudes are in degrees (north and east positive), dates are YYYY-MM-DD and times HH:MM:SS local. Everything is computed locally and deterministically, so it is instant and private. Ideal for solar-tracking, PV-panel-orientation, photography golden-hour, agriculture, shading-analysis and astronomy app developers, sun-path and daylight tools, and STEM teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is the sun's position in the sky; for sunrise and sunset clock times use a sunrise API and for solar irradiance and PV resource a solar-resource API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/solarposition-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 40,000 calls/Mo, 6 req/s
- **Pro** ($18/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($55/Mo) — 1,450,000 calls/Mo, 40 req/s

## Endpoints

### Solar

#### `GET /v1/declination` — Declination & equation of time

**Parameters:**
- `date` (query, required, string) — Date (YYYY-MM-DD) Example: `2024-06-20`
- `time` (query, optional, string) — UT time (HH:MM:SS) Example: `12:00:00`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarposition-api/v1/declination?date=2024-06-20&time=12%3A00%3A00"
```

**Response:**
```json
{
    "data": {
        "note": "Solar declination is the sun's angle north (+) or south (−) of the equator: about +23.44° at the June solstice, −23.44° in December, ~0° at the equinoxes. The equation of time is the apparent-vs-mean solar time difference.",
        "inputs": {
            "date": "2024-06-20",
            "time": "12:00:00"
        },
        "julian_day": 2460482,
        "declination_deg": 23.438149,
        "equation_of_time_min": -1.707428
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:36.842Z",
        "request_id": "f755e263-3519-4105-96da-39b3d5718dc7"
    },
    "status": "ok",
    "message": "Declination",
    "success": true
}
```

#### `GET /v1/position` — Solar position

**Parameters:**
- `latitude` (query, required, string) — Latitude (°, north +) Example: `40`
- `longitude` (query, required, string) — Longitude (°, east +) Example: `0`
- `date` (query, required, string) — Date (YYYY-MM-DD) Example: `2024-06-20`
- `time` (query, optional, string) — Local time (HH:MM:SS) Example: `12:00:00`
- `timezone` (query, optional, string) — UTC offset (hours) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarposition-api/v1/position?latitude=40&longitude=0&date=2024-06-20&time=12%3A00%3A00&timezone=0"
```

**Response:**
```json
{
    "data": {
        "note": "Elevation is the sun's angle above the horizon (negative = below); azimuth is measured clockwise from true north (90°=E, 180°=S, 270°=W). Timezone is the local UTC offset in hours.",
        "inputs": {
            "date": "2024-06-20",
            "time": "12:00:00",
            "latitude": 40,
            "timezone": 0,
            "longitude": 0
        },
        "zenith_deg": 16.565771,
        "azimuth_deg": 178.626274,
        "above_horizon": true,
        "elevation_deg": 73.434229,
        "hour_angle_deg": -0.426857,
        "declination_deg": 23.438149,
        "equation_of_time_min": -1.707428
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:36.943Z",
        "request_id": "2f28c2f2-72f7-4fc7-8e76-91ad032580d1"
    },
    "status": "ok",
    "message": "Solar position",
    "success": true
}
```

#### `GET /v1/solar-noon` — Solar noon & day length

**Parameters:**
- `latitude` (query, required, string) — Latitude (°) Example: `40`
- `longitude` (query, required, string) — Longitude (°) Example: `0`
- `date` (query, required, string) — Date (YYYY-MM-DD) Example: `2024-06-20`
- `timezone` (query, optional, string) — UTC offset (hours) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarposition-api/v1/solar-noon?latitude=40&longitude=0&date=2024-06-20&timezone=0"
```

**Response:**
```json
{
    "data": {
        "note": "Solar noon is when the sun is highest (hour angle 0); peak elevation = 90 − |latitude − declination|. Day length is the geometric time the sun centre is above the horizon (no atmospheric refraction).",
        "inputs": {
            "date": "2024-06-20",
            "latitude": 40,
            "timezone": 0,
            "longitude": 0
        },
        "condition": null,
        "declination_deg": 23.438149,
        "day_length_hours": 14.84429,
        "solar_noon_local": "12:01",
        "max_elevation_deg": 73.438149
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:37.039Z",
        "request_id": "e55f1fe7-83c2-4ea6-8456-35120b624f25"
    },
    "status": "ok",
    "message": "Solar noon",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarposition-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Latitude/longitude in degrees (east & north positive), date YYYY-MM-DD, time HH:MM[:SS] local, timezone the UTC offset in hours. Azimuth is clockwise from true north.",
        "service": "solarposition-api",
        "formulae": {
            "elevation": "sin(elev) = sin(lat)·sin(δ) + cos(lat)·cos(δ)·cos(H)",
            "day_length": "2·acos(−tan(lat)·tan(δ)) / 15  hours",
            "max_elevation": "90 − |latitude − declination|"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/position": "Sun elevation, azimuth, zenith and hour angle for a latitude/longitude, date and local time.",
            "GET /v1/solar-noon": "Solar-noon clock time, peak elevation and day length for a place and date.",
            "GET /v1/declination": "Solar declination and equation of time for a date (no location needed)."
        },
        "description": "Solar position calculator (NOAA algorithm): sun declination and equation of time, elevation/azimuth/zenith for a place and instant, and solar noon, peak elevation and day length."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:37.159Z",
        "request_id": "64657e03-1c57-458d-9740-5f9db365709d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/solarposition-api
OpenAPI spec: https://www.oanor.com/api/solarposition-api/openapi.json