Sign inSign up

dderoussiaux/sunpos-serv

By dderoussiaux

•Updated about 1 month ago

API to retrieve the sun position (azimuth and elevation) for a given position.

Image
0

6.0K

dderoussiaux/sunpos-serv repository overview

⁠Sun Position API Docker Image

⁠🌞 Overview

A Docker container providing REST APIs to calculate sun position (azimuth and elevation) based on geographic coordinates and time. Built with Next.js and SunCalc library.

⁠🚀 Quick Start

⁠Docker Run
docker run -d \
    --name sun-position-api \
    -p 3000:3000 \
    -e TZ=Europe/Paris \
    -e NEXT_PUBLIC_APP_URL=http://localhost:3000 \
    dderoussiaux/sunpos-serv:latest
⁠Docker Compose
services:
    sun-api:
        image: dderoussiaux/sunpos-serv:latest
        container_name: sun-position-api
        ports:
            - "3000:3000"
        environment:
            - TZ=Europe/Paris
            - NEXT_PUBLIC_APP_URL=http://localhost:3000
        restart: unless-stopped

⁠📡 API Endpoints

⁠1. API Documentation

GET /docs

⁠2. Current Sun Position

GET /api/current

⁠3. Daily Sun Positions

GET /api/daily

⁠4. OpenAPI Specification

GET /api/swagger.json

⁠⚙️ Environment Variables

VariableDescriptionDefaultRequired
TZTimezone for date/time formattingUTCNo
NEXT_PUBLIC_APP_URLBase URL for API documentationhttp://localhost:3000⁠No
PORTInternal server port3000No

⁠🐳 Docker Commands

⁠Run with Environment Variables
docker run -d \
    --name sun-position-api \
    -p 3000:3000 \
    -e TZ=America/New_York \
    -e NEXT_PUBLIC_APP_URL=https://api.yourdomain.com \
    dderoussiaux/sunpos-serv:latest
⁠Run with Docker Compose
services:
    sun-position-api:
        image: dderoussiaux/sunpos-serv:latest
        ports:
            - "3000:3000"
        environment:
            - TZ=America/New_York
            - NEXT_PUBLIC_APP_URL=https://api.yourdomain.com
        restart: unless-stopped

⁠📋 Response Examples

⁠Current Position Response
{
    "azimuth": 180.5,
    "elevation": 45.2,
    "timestamp": "2024-01-15T12:00:00.000Z",
    "time_local": "12:00:00",
    "date_local": "Monday January 15, 2024",
    "coordinates": {
        "latitude": 48.8566,
        "longitude": 2.3522
    },
    "timezone": "America/New_York"
}
⁠Daily Positions Response
{
    "date": "Monday January 15, 2024",
    "date_iso": "2024-01-15",
    "sunrise": "2024-01-15T08:45:00.000Z",
    "sunrise_local": "08:45:00",
    "sunset": "2024-01-15T17:30:00.000Z",
    "sunset_local": "17:30:00",
    "interval_minutes": 60,
    "coordinates": {
        "latitude": 48.8566,
        "longitude": 2.3522
    },
    "timezone": "America/New_York",
    "positions": [
        {
            "timestamp": "2024-01-15T08:45:00.000Z",
            "azimuth": 76.44,
            "elevation": -0.58,
            "time": "08:45:00",
            "type": "sunrise_exact"
        }
    ],
    "total_positions": 10,
    "position_types": {
        "sunrise_exact": "Exact position at sunrise",
        "sunset_exact": "Exact position at sunset",
        "rounded_interval": "Position at rounded interval"
    }
}

⁠🔧 Advanced Configuration

⁠Reverse Proxy Setup

When behind a reverse proxy (nginx, traefik, etc.):

environment:
    - NEXT_PUBLIC_APP_URL=https://api.yourdomain.com
    - TZ=UTC
⁠Custom Port
docker run -d \
    --name sun-position-api \
    -p 8080:3000 \
    -e PORT=3000 \
    -e NEXT_PUBLIC_APP_URL=http://localhost:8080 \
    dderoussiaux/sunpos-serv:latest

⁠📊 Health Check

The container includes health checks. Test with:

curl http://localhost:3000/api/current?lat=0&lng=0

⁠🛠️ Technical Details

  • Base Image: Node.js 22 Alpine
  • Framework: Next.js 14
  • Sun Calculations: SunCalc library
  • API Documentation: OpenAPI 3.0 with Swagger UI
  • Health Checks: Built-in container health monitoring

Tag summary

Content type

Image

Digest

sha256:20d7c7af8…

Size

69.2 MB

Last updated

about 1 month ago

docker pull dderoussiaux/sunpos-serv