Portfolio Case Study

Calendula
Astronomical API

A production-grade REST API delivering high-precision sky events — sunrise & sunset, moon phases, solstices, planetary visibility, and ocean tides — for any coordinate on Earth.

🐍 Python 3.12 🌐 Django REST Framework 🌍 PostGIS 🔭 Skyfield 🌊 EOT20 Tides

Live API → Documentation

20+

API Endpoints

Django Apps

~2 GB

Tide model data

What it does

Core capabilities

☀️

Solar Events

Precise sunrise, sunset, civil/nautical/astronomical twilight times for any lat/lng, accounting for atmospheric refraction and elevation.

🌙

Lunar Events

Moon rise/set times, current phase, illumination percentage, and upcoming phase cycle — new moon through full moon and back.

🪐

Planetary Data

Rise, transit, and set times for all major planets. Visibility windows, elongation from the Sun, and angular diameter for any date.

🌊

Ocean Tides

Tidal height predictions using the EOT20 ocean tide model (DOI:10.17882/79489) with 2 GB of harmonic constituent data processed via xarray and Dask.

🗺️

Geographic Reference

Searchable database of cities, countries, timezones, and regions via GeoNames, backed by PostGIS for spatial queries and H3 hexagonal indexing.

💳

Monetisation Built-in

Per-endpoint throttling by membership tier, Stripe-powered checkout, API key issuance/revocation, and a manager-controlled docs portal — all reusable.

Under the hood

Technology stack

Core Framework

Django 4.2 Django REST Framework 3.15 Python 3.12 django-cors-headers django-filter

Database & Geospatial

PostgreSQL + PostGIS psycopg2 H3 (hexagonal grid) pyproj 3.6 Shapely 2.0 timezonefinder

Astronomy & Science

Skyfield 1.54 jplephem (JPL DE421) pyTMD 3.0 (tides) numpy 2.4 scipy 1.17 pandas 3.0

Data Pipeline

xarray 2026.4 Dask (parallel compute) netCDF4 / h5netcdf EOT20 (~2 GB NetCDF)

Auth, Payments & Ops

Stripe 14.4 cryptography / pyOpenSSL Sentry SDK 2.60 django-extensions Pint (units)

Platform Packages (lxcor-*)

kotta — throttling & quotas reggi — auth & API keys billa — Stripe billing docca — docs portal romma — home pages

How it's built

Architecture

Domain Apps

astra

Astronomical computation engine. Wraps Skyfield for sky events, planetary positions, sunrise/sunset, and tide predictions. One file per class, clean architecture throughout.

locci

Geographic reference data service. Cities, countries, timezones, and regions sourced from GeoNames, stored in PostGIS, indexed with H3 hexagons.

Platform Apps (reusable packages)

kotta

Per-endpoint throttling and quota management. Membership tiers (Free / Basic / Pro) with configurable request limits and usage tracking.

reggi

User authentication, API key issuance and revocation, session management, and secure Bearer-token enforcement.

billa

Stripe-powered checkout, subscription tier assignment on payment, and customer portal integration.

docca

Manager-controlled API documentation portal. Auto-discovers registered endpoints and renders structured docs with visibility controls.

Data Pipeline — Tide Modelling

EOT20 Constituent Data

~2 GB of harmonic tidal constituents (17 components) distributed as NetCDF4 files from DOI:10.17882/79489 under CC-BY 4.0.

xarray + Dask

Lazily loaded and chunked via xarray with Dask back-end. Coordinate interpolation extracts per-point amplitude and phase at request time.

pyTMD reconstruction

pyTMD reconstructs the tidal height time-series from constituents for any lat/lng, returning a full 24-hour tide prediction curve.

CalendulaAstronomical API