# Sunrise & Sunset API
> Sunrise, sunset, solar noon, day length and the civil, nautical and astronomical twilight phases for any latitude/longitude and date — plus a multi-day range. Useful for agriculture, solar energy, photography, outdoor scheduling, smart-home automation and astronomy apps.

## 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/sunrise-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 2 req/s
- **Basic** ($8/Mo) — 150,000 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 750,000 calls/Mo, 20 req/s
- **Mega** ($59/Mo) — 3,000,000 calls/Mo, 50 req/s

## Endpoints

### Sun

#### `GET /v1/range` — Sun times for a date range

**Parameters:**
- `lat` (query, required, string) — Latitude Example: `52.52`
- `lng` (query, required, string) — Longitude Example: `13.405`
- `start` (query, required, string) — Start YYYY-MM-DD Example: `2026-06-20`
- `end` (query, required, string) — End YYYY-MM-DD (max 31 days) Example: `2026-06-22`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sunrise-api/v1/range?lat=52.52&lng=13.405&start=2026-06-20&end=2026-06-22"
```

**Response:**
```json
{
    "data": {
        "end": "2026-06-22",
        "lat": 52.52,
        "lng": 13.405,
        "days": [
            {
                "date": "2026-06-20",
                "sunset": "2026-06-20T19:35:19+00:00",
                "sunrise": "2026-06-20T02:40:38+00:00",
                "day_length": {
                    "hours": 16.91,
                    "seconds": 60881,
                    "formatted": "16h 54m"
                },
                "solar_noon": "2026-06-20T11:07:58+00:00"
            },
            {
                "date": "2026-06-21",
                "sunset": "2026-06-21T19:35:33+00:00",
                "sunrise": "2026-06-21T02:40:50+00:00",
                "day_length": {
                    "hours": 16.91,
                    "seconds": 60883,
                    "formatted": "16h 54m"
                },
                "solar_noon": "2026-06-21T11:08:12+00:00"
            },
            {
                "date": "2026-06-22",
                "sunset": "2026-06-22T19:35:44+00:00",
                "sunrise": "2026-06-22T02:41:05+00:00",
                "day_length": {
                    "hours": 16.91,
                    "seconds": 60879,
                    "formatted": "16h 54m"
                },
                "solar_noon": "2026-06-22T11:08:25+00:00"
            }
        ],
        "count": 3,
        "start": "2026-06-20",
        "times_in": "UTC"
    },
    "meta": {
        "timestamp": "2026-05-30T03:39:09.965Z",
        "request_id": "
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/times` — Sun times for one date

**Parameters:**
- `lat` (query, required, string) — Latitude Example: `52.52`
- `lng` (query, required, string) — Longitude Example: `13.405`
- `date` (query, optional, string) — YYYY-MM-DD (default today)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sunrise-api/v1/times?lat=52.52&lng=13.405"
```

**Response:**
```json
{
    "data": {
        "lat": 52.52,
        "lng": 13.405,
        "date": "today",
        "sunset": "2026-05-30T19:18:58+00:00",
        "sunrise": "2026-05-30T02:48:54+00:00",
        "times_in": "UTC",
        "day_length": {
            "hours": 16.5,
            "seconds": 59404,
            "formatted": "16h 30m"
        },
        "solar_noon": "2026-05-30T11:03:56+00:00",
        "civil_twilight": {
            "end": "2026-05-30T20:03:51+00:00",
            "begin": "2026-05-30T02:04:01+00:00"
        },
        "nautical_twilight": {
            "end": "2026-05-30T21:15:21+00:00",
            "begin": "2026-05-30T00:52:31+00:00"
        },
        "astronomical_twilight": {
            "end": "1970-01-01T00:00:01+00:00",
            "begin": "1970-01-01T00:00:01+00:00"
        }
    },
    "meta": {
        "timestamp": "2026-05-30T03:39:21.837Z",
        "request_id": "099adf8b-aa43-49bf-bac0-616c80f102cd"
    },
    "status": "ok",
    "message": "Sun times retrieved successfully",
    "success": true
}
```


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