<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Conducting Chronolocation Investigation

## SunCalc

### Python Library

```python
from suncalc import get_position, get_times
from datetime import datetime, timezone

# Sun position (azimuth + altitude)
pos = get_position(datetime(2026, 3, 15, 14, 0, tzinfo=timezone.utc), 48.8566, 2.3522)

# Sun times (sunrise, sunset, golden hour, etc.)
times = get_times(datetime(2026, 3, 15, tzinfo=timezone.utc), 48.8566, 2.3522)
```

### Key Return Values

| Field | Description |
|---|---|
| `azimuth` | Sun direction in radians (0 = south, π/2 = west) |
| `altitude` | Sun elevation in radians above horizon |

## Shadow Geometry

| Formula | Description |
|---|---|
| `tan(elevation) = object_height / shadow_length` | Sun elevation from shadow |
| `azimuth = shadow_direction + 180°` | Sun direction from shadow direction |

## ExifTool Temporal Tags

| Tag | Description |
|---|---|
| `DateTimeOriginal` | When the photo was taken |
| `CreateDate` | File creation timestamp |
| `ModifyDate` | Last modification timestamp |
| `GPSDateTime` | GPS-derived UTC timestamp |

## Agent Script

```bash
# Sun position at location and time
node agent.js sun-position --lat 48.8566 --lon 2.3522 --date 2026-03-15 --time 14:00

# Estimate time from shadow measurements
node agent.js shadow-time --lat 48.8566 --lon 2.3522 --date 2026-03-15 --shadow-length 2.5 --object-height 1.8

# Extract timestamps from image
node agent.js extract-timestamps photo.jpg

# Weather verification
node agent.js weather-check --lat 48.8566 --lon 2.3522 --date 2026-03-15
```

## Weather History APIs

| Service | URL |
|---|---|
| Open-Meteo Archive | `https://archive-api.open-meteo.com/v1/archive` |
| Weather Underground | `https://www.wunderground.com/history/` |
| NOAA Climate Data | `https://www.ncdc.noaa.gov/cdo-web/` |
