# Sundial API
> Sundial gnomonics maths as an API, computed locally and deterministically — the hour-line, gnomon and longitude-correction numbers a dial maker, horologist or astronomy hobbyist lays a sundial out with. The hour-line-angle endpoint gives the angle of each hour line on the dial plate, measured from the noon line: for a horizontal dial tan(angle) = sin(latitude) × tan(hour angle), and for a vertical south-facing dial cos(latitude) is used instead, where the hour angle is 15° per hour from solar noon. At 50° latitude the 1-o'clock line sits about 11.6° from noon rather than 15° — the lines bunch near noon and spread toward the ends, which is exactly why a sundial's hours are unevenly spaced. The gnomon endpoint gives the style angle: the gnomon's shadow-casting edge must point at the celestial pole, so it rises at the latitude angle on a horizontal dial (50° at 50° N) and at 90° − latitude on a vertical dial — get this wrong and the dial keeps correct time at only one season. The longitude-correction endpoint converts the dial's local apparent time to clock time: 4 minutes of time per degree of longitude, correction = 4 × (reference meridian − local longitude), so a dial at 7.5° E on Central European Time reads 30 minutes slow versus the clock. Everything is computed locally and deterministically, so it is instant and private. Ideal for sundial-design and gnomonics tools, astronomy-education and maker apps, and horology calculators. Pure local computation — no key, no third-party service, instant. Add the equation of time for full clock accuracy. 3 compute endpoints. For the sun's position use a solar-position API; for sunrise and sunset a sunrise 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/sundial-api/..."
```

## Pricing
- **Free** (Free) — 7,050 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 59,500 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 246,000 calls/Mo, 15 req/s
- **Mega** ($73/Mo) — 1,135,000 calls/Mo, 40 req/s

## Endpoints

### Sundial

#### `GET /v1/gnomon` — Gnomon (style) angle

**Parameters:**
- `latitude_deg` (query, required, string) — Latitude (degrees) Example: `50`
- `dial_type` (query, optional, string) — horizontal or vertical (default horizontal) Example: `horizontal`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sundial-api/v1/gnomon?latitude_deg=50&dial_type=horizontal"
```

**Response:**
```json
{
    "data": {
        "note": "The gnomon's straight edge (the 'style') must point at the celestial pole, parallel to Earth's axis, so its angle above the dial plate is fixed by the latitude: on a horizontal dial the style rises at the latitude angle (50° at 50° N); on a vertical south dial it is 90° − latitude. Get this angle right and the shadow keeps correct time year-round; get it wrong and the dial reads accurately at only one season.",
        "inputs": {
            "dial_type": "horizontal",
            "latitude_deg": 50
        },
        "style_angle_deg": 50
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:49.811Z",
        "request_id": "b3dc1ca3-1cf5-4167-bcfe-f66c56a1b8fb"
    },
    "status": "ok",
    "message": "Gnomon angle",
    "success": true
}
```

#### `GET /v1/hour-line-angle` — Hour-line angle on the dial

**Parameters:**
- `latitude_deg` (query, required, string) — Latitude (degrees, N positive) Example: `50`
- `hour_angle_deg` (query, required, string) — Hour angle from solar noon (15°/hour) Example: `15`
- `dial_type` (query, optional, string) — horizontal or vertical (default horizontal) Example: `horizontal`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sundial-api/v1/hour-line-angle?latitude_deg=50&hour_angle_deg=15&dial_type=horizontal"
```

**Response:**
```json
{
    "data": {
        "note": "The hour-line angle on the dial plate, measured from the noon (12:00) line: for a horizontal dial tan(angle) = sin(latitude) × tan(hour angle); for a vertical south-facing dial it is cos(latitude) instead. The hour angle is 15° per hour from solar noon (1 pm = 15°, 2 pm = 30°). At 50° latitude the 1-o'clock line sits about 11.6° from noon, not 15° — the lines bunch near noon and spread toward the ends, which is why a sundial's hours are unevenly spaced.",
        "inputs": {
            "dial_type": "horizontal",
            "latitude_deg": 50,
            "hour_angle_deg": 15
        },
        "hour_line_angle_deg": 11.5995
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:49.912Z",
        "request_id": "c99c1664-125f-4e84-b8ba-530b6d616006"
    },
    "status": "ok",
    "message": "Hour-line angle",
    "success": true
}
```

#### `GET /v1/longitude-correction` — Longitude time correction

**Parameters:**
- `local_longitude_deg` (query, required, string) — Local longitude (degrees, E positive) Example: `7.5`
- `reference_meridian_deg` (query, required, string) — Time-zone reference meridian (degrees, E positive) Example: `15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sundial-api/v1/longitude-correction?local_longitude_deg=7.5&reference_meridian_deg=15"
```

**Response:**
```json
{
    "data": {
        "note": "A sundial reads local apparent (solar) time, but clocks run on a zone's reference meridian, so you add a longitude correction: 4 minutes of time per degree of longitude — correction = 4 × (reference meridian − local longitude), east positive. A dial at 7.5° E on Central European Time (15° E) reads 30 minutes slow versus the clock, so add 30 minutes. (For full clock time also apply the equation of time, which varies through the year.)",
        "inputs": {
            "local_longitude_deg": 7.5,
            "reference_meridian_deg": 15
        },
        "correction_minutes": 30
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:50.007Z",
        "request_id": "d2cb961c-d27b-45fc-aada-9fde4cff6040"
    },
    "status": "ok",
    "message": "Longitude correction",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Degrees; correction in minutes. horizontal: tan(angle)=sin(lat)·tan(HA), style=lat; vertical-south: cos(lat), style=90−lat; longitude correction = 4·(ref−local) min. Add the equation of time for clock time. For the sun's position use a solar-position API.",
        "service": "sundial-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/gnomon": "Gnomon (style) angle from latitude and dial type.",
            "GET /v1/hour-line-angle": "Hour-line angle from latitude, hour angle and dial type.",
            "GET /v1/longitude-correction": "Time correction in minutes from local and reference longitude."
        },
        "description": "Sundial gnomonics: hour-line angle (horizontal/vertical dial), gnomon style angle, and longitude time correction."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:50.106Z",
        "request_id": "dcef5167-a0b1-4745-ab33-2300d004dd22"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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