{"openapi":"3.0.3","info":{"title":"Orbitalio API","version":"1.0.0","description":"Earth's Orbital Dynamics and Rotation Parameters\n\nOrbitalio provides comprehensive calculations for Earth's orbital mechanics, Milankovitch cycles,\nrotation evolution, and long-term astronomical parameters. Essential for paleoclimate research,\nclimate modeling, and astronomical applications.\n\n## Features\n- Milankovitch Cycles (eccentricity, obliquity, precession)\n- Solar insolation calculations\n- Climate forcing indices\n- Keplerian orbital elements\n- Earth rotation evolution (tidal deceleration)\n- Moon-Earth system dynamics\n- Historical day length from geological evidence\n- Integrated timeline data\n","contact":{"name":"Orbitalio Support","email":"support@orbitalio.org"},"license":{"name":"Internal use","url":"https://ppn-hub.com/license"}},"servers":[{"url":"https://api.orbitalio.org","description":"Production server"},{"url":"http://localhost:8787","description":"Local development"}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"healthCheck","tags":["General"],"security":[],"responses":{"200":{"description":"Service is healthy"}}}},"/milankovitch/cycles":{"get":{"summary":"Get Milankovitch orbital parameters (eccentricity/obliquity/precession) for a year.","description":"Returns the three Milankovitch cycles for Earth's orbit at a given\nyear: orbital eccentricity, axial obliquity (tilt), and axial\nprecession. These drive long-term climate cycles (~26 kyr / 41 kyr /\n100 kyr) and ice-age timing.\n","operationId":"getMilankovitchCycles","tags":["Milankovitch"],"security":[],"parameters":[{"name":"year","in":"query","schema":{"type":"integer"},"description":"Year (negative for BCE), default 0","example":2024}],"responses":{"200":{"description":"Orbital parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"year":{"type":"integer"},"eccentricity":{"type":"number"},"obliquity_degrees":{"type":"number"},"precession_parameter":{"type":"number"},"longitude_perihelion_degrees":{"type":"number"}}},"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string"},"reference":{"type":"string","example":"Berger (1978), Laskar (2004)"}}}}}}}}}}},"/milankovitch/insolation":{"get":{"summary":"Calculate solar insolation (W/m²) at a latitude for a year/season.","description":"Returns the top-of-atmosphere solar insolation (W/m²) at a given\nlatitude, year, and season — derived from the Milankovitch orbital\nparameters. Use for paleoclimate modelling, glacial-cycle analysis,\nand solar-energy long-term trend studies.\n","operationId":"getInsolation","tags":["Milankovitch"],"security":[],"parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude coordinate in decimal degrees","example":35.6812},{"name":"year","in":"query","schema":{"type":"integer","default":0},"description":"Year for the query","example":2024}],"responses":{"200":{"description":"Insolation data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"latitude":{"type":"number"},"year":{"type":"integer"},"annual_mean_w_m2":{"type":"number"},"summer_solstice_w_m2":{"type":"number"},"winter_solstice_w_m2":{"type":"number"},"anomaly_from_present_w_m2":{"type":"number"},"anomaly_percent":{"type":"number"}}}}}}}}}}},"/milankovitch/climate-forcing":{"get":{"summary":"Estimate climate-forcing index (glacial vs interglacial) for a year.","description":"Returns a normalised climate-forcing index combining Milankovitch\ncycles with greenhouse-gas estimates. Use for paleoclimate\nreconstructions and to position any year relative to known\nglacial/interglacial phases over the last 800 kyr.\n","operationId":"getClimateForcing","tags":["Milankovitch"],"security":[],"parameters":[{"name":"year","in":"query","schema":{"type":"integer","default":0},"description":"Year for the query","example":2024}],"responses":{"200":{"description":"Climate forcing data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"year":{"type":"integer"},"glacial_index":{"type":"number","description":"0-1 scale (0=interglacial, 1=glacial maximum)"},"temperature_anomaly_c":{"type":"number"},"sea_level_change_m":{"type":"number"},"ice_sheet_volume_km3":{"type":"number"},"confidence":{"type":"number"}}}}}}}}}}},"/orbital/keplerian":{"get":{"summary":"Get Earth's complete Keplerian orbital elements at an instant.","description":"Returns the six classical Keplerian orbital elements (semi-major axis,\neccentricity, inclination, longitude of ascending node, argument of\nperiapsis, true anomaly) describing Earth's orbit around the Sun at a\nspecific instant. Use for orbit visualisation and propagation.\n","operationId":"getKeplerianElements","tags":["Orbital"],"security":[],"parameters":[{"name":"year","in":"query","schema":{"type":"integer"},"description":"Year for the query","example":2024}],"responses":{"200":{"description":"Keplerian elements","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"year":{"type":"integer"},"semi_major_axis_au":{"type":"number"},"eccentricity":{"type":"number"},"inclination_degrees":{"type":"number"},"longitude_ascending_node":{"type":"number"},"longitude_perihelion":{"type":"number"},"mean_anomaly":{"type":"number"},"true_anomaly":{"type":"number"},"derived":{"type":"object","properties":{"perihelion_au":{"type":"number"},"aphelion_au":{"type":"number"},"perihelion_km":{"type":"number"},"aphelion_km":{"type":"number"}}}}}}}}}}}}},"/orbital/earth-sun-distance":{"get":{"summary":"Compute the Earth-Sun distance (AU and km) for a date.","description":"Returns the geocentric Sun distance for any date, varying between\n~0.983 AU (perihelion, January) and ~1.017 AU (aphelion, July).\nUseful for solar-flux scaling, eclipse magnitude prediction, and\nseasonal-irradiance modelling.\n","operationId":"getEarthSunDistance","tags":["Orbital"],"security":[],"parameters":[{"name":"date","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date (YYYY-MM-DD), default today","example":"2024-01-15"}],"responses":{"200":{"description":"Earth-Sun distance","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"distance_au":{"type":"number"},"distance_km":{"type":"number"},"velocity_km_s":{"type":"number"},"light_time_minutes":{"type":"number"}}}}}}}}}}},"/rotation/current":{"get":{"summary":"Get Earth's current rotation parameters (UT1-UTC, LOD, axis position).","description":"Returns the live IERS Earth-rotation snapshot: UT1-UTC offset\n(milliseconds), length-of-day (LOD) deviation, and polar-motion (xp,\nyp) coordinates. Use for time-of-day adjustments, geodesy, and\nastronomical pointing.\n","operationId":"getCurrentRotation","tags":["Rotation"],"security":[],"responses":{"200":{"description":"Current rotation parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"year":{"type":"integer"},"day_length_hours":{"type":"number"},"day_length_seconds":{"type":"number"},"days_per_year":{"type":"number"},"angular_velocity_rad_s":{"type":"number"},"tidal_deceleration_rate":{"type":"number"}}}}}}}}}}},"/rotation/historical":{"get":{"summary":"Get historical day length over geological time (millions of years).","description":"Returns Earth's day length back through geological time (down to ~1\nbillion years), reconstructed from coral and stromatolite growth-band\nevidence and tidal-friction modelling. Useful for paleoclimate and\npaleontology research.\n","operationId":"getHistoricalRotation","tags":["Rotation"],"security":[],"parameters":[{"name":"year","in":"query","schema":{"type":"integer"},"description":"Year BP (Before Present)","example":2024}],"responses":{"200":{"description":"Historical rotation data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"year":{"type":"integer"},"day_length_hours":{"type":"number"},"day_length_seconds":{"type":"number"},"days_per_year":{"type":"number"},"angular_velocity_rad_s":{"type":"number"}}},"metadata":{"type":"object","properties":{"reference":{"type":"string"}}}}}}}}}}},"/moon/distance":{"get":{"summary":"Compute the Moon-Earth distance (km) for a date.","description":"Returns the geocentric Moon distance for any date, varying between\n~356,500 km (perigee) and ~406,700 km (apogee). Useful for tide\namplitude modelling, supermoon prediction, and parallax corrections.\n","operationId":"getMoonDistance","tags":["Moon"],"security":[],"parameters":[{"name":"year","in":"query","schema":{"type":"integer"},"description":"Year for the query","example":2024}],"responses":{"200":{"description":"Moon distance data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"year":{"type":"integer"},"distance_km":{"type":"number"},"orbital_period_days":{"type":"number"},"tidal_force_relative":{"type":"number"}}}}}}}}}}},"/timeline/integrated":{"get":{"summary":"Get an integrated timeline of orbital + rotation + climate parameters.","description":"Returns a unified timeline combining Milankovitch cycles, rotation\nparameters, climate-forcing index, and key orbital events over the\nconfigured year range. Use as a single feed for visualisations and\ncomparative analysis across the last million years or future\nprojections.\n","operationId":"getIntegratedTimeline","tags":["Timeline"],"security":[],"parameters":[{"name":"start","in":"query","schema":{"type":"integer","default":-10000},"description":"Start value or index","example":0},{"name":"end","in":"query","schema":{"type":"integer","default":10000},"description":"End value or index","example":100},{"name":"interval","in":"query","schema":{"type":"integer","default":1000},"description":"Time interval between data points","example":1000}],"responses":{"200":{"description":"Comprehensive timeline data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"timeline":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer"},"orbital":{"type":"object"},"rotation":{"type":"object"},"lunar":{"type":"object"},"climate_implications":{"type":"object"}}}},"total_points":{"type":"integer"},"interval_years":{"type":"integer"}}}}}}}}}}},"/moon/tidal-evolution":{"get":{"summary":"Estimate the Moon's tidal-evolution drift over a span of years.","description":"Returns the projected change in Earth-Moon distance due to tidal\nfriction (currently ~3.8 cm/year) over a configurable time window.\nUseful for long-term geophysical and paleoclimate modelling.\n","operationId":"getTidalEvolution","tags":["Lunar"],"security":[],"parameters":[{"name":"years_ahead","in":"query","required":false,"description":"How many years into the future to project (negative for past).","example":1000,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Tidal-evolution projection"}}}},"/orbital/perihelion":{"get":{"summary":"Get the date and details of Earth's nearest annual perihelion.","description":"Returns the date/time of perihelion (closest approach to the Sun) for\nthe requested year, along with the Earth-Sun distance at that moment.\nUse for orbital-mechanics scheduling and seasonal-irradiance modelling.\n","operationId":"getPerihelion","tags":["Orbital"],"security":[],"parameters":[{"name":"year","in":"query","required":false,"description":"Year to compute perihelion for. Defaults to current year.","example":2026,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Perihelion event details"}}}},"/rotation/lod":{"get":{"summary":"Get current/historical Length-of-Day (LOD) deviation from 86400 s.","description":"Returns the deviation of the actual length-of-day from 86400 seconds\n(typically a few milliseconds), as published by IERS Earth-rotation\nbulletins. Useful for high-precision timing, geodesy, and leap-second\nforecasting.\n","operationId":"getLengthOfDay","tags":["Earth Rotation"],"security":[],"parameters":[{"name":"at","in":"query","required":false,"description":"ISO date for the LOD value. Defaults to today.","example":"2026-05-10","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"LOD value at the requested date"}}}},"/rotation/nutation":{"get":{"summary":"Get Earth's nutation (small periodic axis wobble) parameters.","description":"Returns the current nutation in longitude (Δψ) and obliquity (Δε)\n— short-period oscillations of Earth's rotation axis caused by\ngravitational pull from the Moon and Sun. Essential for precise\ncelestial-coordinate transformations.\n","operationId":"getNutation","tags":["Earth Rotation"],"security":[],"parameters":[{"name":"at","in":"query","required":false,"description":"ISO date/time for the nutation values. Defaults to now.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Nutation parameters"}}}},"/rotation/polar-motion":{"get":{"summary":"Get Earth's polar motion (xp, yp) coordinates.","description":"Returns the polar-motion offset (xp, yp in arcseconds) — the wandering\nof Earth's rotation axis relative to the crust, including the Chandler\nwobble and annual oscillation. Critical for high-precision GPS,\ngeodesy, and astrometric reductions.\n","operationId":"getPolarMotion","tags":["Earth Rotation"],"security":[],"parameters":[{"name":"at","in":"query","required":false,"description":"ISO date for the polar-motion values. Defaults to today.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Polar-motion coordinates"}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication. Obtain from the PPN Hub developer portal."}}},"tags":[{"name":"General","description":"General API information"},{"name":"Milankovitch","description":"Milankovitch cycles and climate forcing"},{"name":"Orbital","description":"Earth's orbital elements"},{"name":"Rotation","description":"Earth rotation evolution"},{"name":"Moon","description":"Moon-Earth system dynamics"},{"name":"Timeline","description":"Integrated historical data"}],"security":[{"ApiKeyAuth":[]}]}