Sun Position Calculator API: The Complete Guide

Need to know where the sun is in the sky at any location and time? This guide covers everything about sun position calculation via API, including solar elevation, azimuth, sunrise/sunset times, and implementation examples.

What is Sun Position?

Sun position refers to where the sun appears in the sky from a specific location at a given time. It's described by two angles: elevation (altitude) and azimuth (compass direction).

These calculations are essential for solar energy, photography, architecture, agriculture, and many other fields.

Solar Geometry Explained

Elevation (Altitude)

The angle between the sun and the horizon, measured in degrees:

• 0° = Sun on the horizon
• 90° = Sun directly overhead (zenith)
• Negative values = Sun below horizon (night)

Azimuth

The compass direction of the sun, measured in degrees from true north:

• 0° = North
• 90° = East
• 180° = South
• 270° = West

Using the Sun Position API

TinyFn provides a comprehensive endpoint for sun position calculations:

POST https://api.tinyfn.io/v1/geo/sun-position
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "lat": 40.7128,
  "lng": -74.0060,
  "timestamp": "2024-06-21T12:00:00Z"
}

{
  "position": {
    "elevation": 72.45,
    "azimuth": 178.32
  },
  "times": {
    "sunrise": "2024-06-21T05:24:00Z",
    "sunset": "2024-06-21T20:31:00Z",
    "solar_noon": "2024-06-21T12:57:00Z",
    "golden_hour_start": "2024-06-21T19:23:00Z",
    "golden_hour_end": "2024-06-21T20:31:00Z"
  },
  "day_length_hours": 15.12
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/geo/sun-position',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      lat: 40.7128,
      lng: -74.0060,
      timestamp: new Date().toISOString()
    })
  }
);
const data = await response.json();
console.log(`Sun elevation: ${data.position.elevation}°`);
console.log(`Sun azimuth: ${data.position.azimuth}°`);

Python

import requests
from datetime import datetime

response = requests.post(
    'https://api.tinyfn.io/v1/geo/sun-position',
    headers={'X-API-Key': 'your-api-key'},
    json={
        'lat': 40.7128,
        'lng': -74.0060,
        'timestamp': datetime.utcnow().isoformat() + 'Z'
    }
)
data = response.json()
print(f"Sun elevation: {data['position']['elevation']}°")
print(f"Sun azimuth: {data['position']['azimuth']}°")

cURL

curl -X POST "https://api.tinyfn.io/v1/geo/sun-position" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "timestamp": "2024-06-21T12:00:00Z"
  }'

Common Use Cases

• Solar Panel Optimization: Calculate optimal panel angles throughout the day
• Photography: Find golden hour and best lighting conditions
• Architecture: Design buildings considering sun angles for natural lighting
• Agriculture: Plan planting and irrigation based on sun exposure
• Smart Home: Automate blinds and lighting based on sun position

Best Practices

1. Use UTC timestamps: Convert to UTC to avoid timezone confusion
2. Cache daily data: Sun times change slowly; cache results for the day
3. Handle polar regions: Be aware of midnight sun and polar night conditions
4. Consider atmospheric refraction: The sun appears higher than geometrically calculated near horizon

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-geo": {
      "url": "https://api.tinyfn.io/mcp/geo/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all geolocation tools available via MCP in our Geolocation MCP Tools for AI Agents guide.