{"openapi":"3.1.0","info":{"title":"Api","version":"0.0.1","description":"Sun and Moon from JPL DE440, checked against Skyfield. One endpoint per question: /v1/position (an instant), /v1/track (paths over a window), /v1/day (rise, set, twilight), /v1/crossing (when a body reaches an altitude), /v1/alignment (where to stand so the body sits on a landmark), POST /v1/alignment/search (every pass over an area you can stand in), /v1/sightline (does the line of sight clear), /v1/magnetic (declination), /v1/weather (nearest METAR).\n\nOne vocabulary: lat, lon, height, heightRef (you); targetLat, targetLon, targetHeight, targetHeightRef (the landmark); body; time | start, end | date, tz; stepSeconds; temperature, pressure, horizon, horizonProfile, dut1; aim; include. Unknown parameters are rejected. Errors: 400 InvalidRequest names the parameter and what is allowed; 503 Unavailable when a data source fails. Every response carries conventions (every threshold and model used) and provenance."},"paths":{"/v1/position":{"get":{"tags":["sky"],"operationId":"sky.position","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"time","in":"query","schema":{"type":"string"},"required":false},{"name":"temperature","in":"query","schema":{"type":"string"},"required":false},{"name":"pressure","in":"query","schema":{"type":"string"},"required":false},{"name":"horizon","in":"query","schema":{"anyOf":[{"type":"string","enum":["sea","geometric"]},{"type":"string"}]},"required":false},{"name":"dut1","in":"query","schema":{"type":"string"},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"time":{"type":"object","properties":{"utc":{"type":"string"},"jdTT":{"type":"number"},"jdUT1":{"type":"number"},"dut1":{"type":"number"},"deltaT":{"type":"number"}},"required":["utc","jdTT","jdUT1","dut1","deltaT"],"additionalProperties":false},"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"sun":{"type":"object","properties":{"azimuth":{"type":"number"},"altitude":{"type":"number"},"apparentAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refracted altitude, degrees; null when it would lie below the observer's horizon or the refraction model's floor (conventions.refraction.validFrom). CHANGED 2026-10-29: was always a number, and repeated the true altitude below −1°."},"altitudeRate":{"type":"number","description":"d(altitude)/dt, degrees per minute (true altitude; analytic from the DE440 velocity, no finite difference)."},"azimuthRate":{"type":"number","description":"d(azimuth)/dt, degrees per minute (symmetric difference over ±10 s)."},"rightAscension":{"type":"number"},"declination":{"type":"number"},"distanceKm":{"type":"number"},"angularRadius":{"type":"number"},"eclipticLongitude":{"type":"number"},"eclipticLatitude":{"type":"number"}},"required":["azimuth","altitude","apparentAltitude","altitudeRate","azimuthRate","rightAscension","declination","distanceKm","angularRadius","eclipticLongitude","eclipticLatitude"],"additionalProperties":false},"moon":{"type":"object","properties":{"azimuth":{"type":"number"},"altitude":{"type":"number"},"apparentAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refracted altitude, degrees; null when it would lie below the observer's horizon or the refraction model's floor (conventions.refraction.validFrom). CHANGED 2026-10-29: was always a number, and repeated the true altitude below −1°."},"altitudeRate":{"type":"number","description":"d(altitude)/dt, degrees per minute (true altitude; analytic from the DE440 velocity, no finite difference)."},"azimuthRate":{"type":"number","description":"d(azimuth)/dt, degrees per minute (symmetric difference over ±10 s)."},"rightAscension":{"type":"number"},"declination":{"type":"number"},"distanceKm":{"type":"number"},"angularRadius":{"type":"number"},"eclipticLongitude":{"type":"number"},"eclipticLatitude":{"type":"number"},"phase":{"type":"object","properties":{"phaseAngle":{"type":"number"},"illuminatedFraction":{"type":"number"},"elongation":{"type":"number"},"brightLimbAngle":{"type":"number"},"name":{"type":"string","enum":["new","waxing crescent","first quarter","waxing gibbous","full","waning gibbous","last quarter","waning crescent"]}},"required":["phaseAngle","illuminatedFraction","elongation","brightLimbAngle","name"],"additionalProperties":false},"brightLimbAngleFromVertical":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Bright limb seen from this observer: degrees clockwise from the local vertical (the direction towards the zenith) as the observer sees the sky, i.e. towards increasing azimuth; topocentric (phase.brightLimbAngle is geocentric, from celestial north through east). = 360° − (χ − q) with χ the topocentric bright-limb position angle and q the parallactic angle. null at the zenith."}},"required":["azimuth","altitude","apparentAltitude","altitudeRate","azimuthRate","rightAscension","declination","distanceKm","angularRadius","eclipticLongitude","eclipticLatitude","phase","brightLimbAngleFromVertical"],"additionalProperties":false},"conventions":{"type":"object","properties":{"refraction":{"type":"object","properties":{"model":{"type":"string"},"temperatureC":{"type":"number"},"pressureHpa":{"type":"number"},"validFrom":{"type":"number","description":"Lowest apparent altitude that gets a value: max(horizon, the model floor −1.6963°). Below it apparentAltitude is null."},"validTo":{"type":"number"},"uncertainty":{"type":"string"}},"required":["model","temperatureC","pressureHpa","validFrom","validTo","uncertainty"],"additionalProperties":false},"horizon":{"type":"object","properties":{"kind":{"type":"string","enum":["sea","geometric","custom","profile"]},"altitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Apparent altitude of the horizon, degrees (null for a profile)."},"dip":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sea-horizon dip, degrees: √(1 − k)·acos(R/(R + heightMsl)), k = terrestrialRefractionK, R = 6 371 008.8 m."},"terrestrialRefractionK":{"type":"number"},"profile":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"azimuth":{"type":"number"},"elevation":{"type":"number"}},"required":["azimuth","elevation"],"additionalProperties":false}},{"type":"null"}]}},"required":["kind","altitude","dip","terrestrialRefractionK","profile"],"additionalProperties":false},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false},"rates":{"type":"object","properties":{"unit":{"type":"string","enum":["deg/min"]},"method":{"type":"string"}},"required":["unit","method"],"additionalProperties":false}},"required":["refraction","horizon","geoid","rates"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["time","observer","sun","moon","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/day":{"get":{"tags":["sky"],"operationId":"sky.day","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"date","in":"query","schema":{"type":"string"},"required":true},{"name":"tz","in":"query","schema":{"type":"string"},"required":true},{"name":"temperature","in":"query","schema":{"type":"string"},"required":false},{"name":"pressure","in":"query","schema":{"type":"string"},"required":false},{"name":"horizon","in":"query","schema":{"anyOf":[{"type":"string","enum":["sea","geometric"]},{"type":"string"}]},"required":false},{"name":"horizonProfile","in":"query","schema":{"type":"string"},"required":false},{"name":"aim","in":"query","schema":{"type":"string","enum":["upper","center","lower"]},"required":false},{"name":"dut1","in":"query","schema":{"type":"string"},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"tz":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"body":{"type":"string","enum":["sun","moon"]},"kind":{"type":"string","enum":["rise","set","transit","civilDawn","civilDusk","nauticalDawn","nauticalDusk","astronomicalDawn","astronomicalDusk","goldenHourStart","goldenHourEnd","blueHourStart","blueHourEnd"]}},"required":["time","body","kind"],"additionalProperties":false}},"conventions":{"type":"object","properties":{"riseSet":{"type":"object","properties":{"aim":{"type":"object","properties":{"point":{"type":"string","enum":["upper","center","lower"]},"definition":{"type":"string"}},"required":["point","definition"],"additionalProperties":false},"definition":{"type":"string"},"horizon":{"type":"object","properties":{"kind":{"type":"string","enum":["sea","geometric","custom","profile"]},"altitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Apparent altitude of the horizon, degrees (null for a profile)."},"dip":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sea-horizon dip, degrees: √(1 − k)·acos(R/(R + heightMsl)), k = terrestrialRefractionK, R = 6 371 008.8 m."},"terrestrialRefractionK":{"type":"number"},"profile":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"azimuth":{"type":"number"},"elevation":{"type":"number"}},"required":["azimuth","elevation"],"additionalProperties":false}},{"type":"null"}]}},"required":["kind","altitude","dip","terrestrialRefractionK","profile"],"additionalProperties":false},"refraction":{"type":"object","properties":{"model":{"type":"string"},"temperatureC":{"type":"number"},"pressureHpa":{"type":"number"},"atHorizon":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refraction at the horizon altitude, degrees (null for a profile: it varies with azimuth)."}},"required":["model","temperatureC","pressureHpa","atHorizon"],"additionalProperties":false},"trueLimbAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"True (vacuum) altitude of the chosen limb at rise/set = horizon altitude − refraction (null for a profile)."}},"required":["aim","definition","horizon","refraction","trueLimbAltitude"],"additionalProperties":false},"transit":{"type":"string"},"twilight":{"type":"object","properties":{"quantity":{"type":"string"},"civil":{"type":"number"},"nautical":{"type":"number"},"astronomical":{"type":"number"}},"required":["quantity","civil","nautical","astronomical"],"additionalProperties":false},"goldenHour":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"}},"required":["from","to"],"additionalProperties":false},"blueHour":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"}},"required":["from","to"],"additionalProperties":false},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false}},"required":["riseSet","transit","twilight","goldenHour","blueHour","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["date","tz","start","end","observer","events","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/crossing":{"get":{"tags":["sky"],"operationId":"sky.crossing","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"body","in":"query","schema":{"type":"string","enum":["sun","moon"]},"required":true},{"name":"altitude","in":"query","schema":{"type":"string"},"required":false},{"name":"altitudeType","in":"query","schema":{"type":"string","enum":["true","apparent"]},"required":false},{"name":"horizonProfile","in":"query","schema":{"type":"string"},"required":false},{"name":"direction","in":"query","schema":{"type":"string","enum":["rise","set","either"]},"required":false},{"name":"start","in":"query","schema":{"type":"string"},"required":false},{"name":"end","in":"query","schema":{"type":"string"},"required":false},{"name":"date","in":"query","schema":{"type":"string"},"required":false},{"name":"tz","in":"query","schema":{"type":"string"},"required":false},{"name":"temperature","in":"query","schema":{"type":"string"},"required":false},{"name":"pressure","in":"query","schema":{"type":"string"},"required":false},{"name":"dut1","in":"query","schema":{"type":"string"},"required":false},{"name":"include","in":"query","schema":{"type":"string"},"required":false},{"name":"aim","in":"query","schema":{"type":"string","enum":["center","upper","lower","litCentroid"]},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","enum":["sun","moon"]},"start":{"type":"string"},"end":{"type":"string"},"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"crossings":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"direction":{"type":"string","enum":["rise","set"]},"azimuth":{"type":"number"},"altitude":{"type":"number","description":"True altitude of the body centre at the crossing."},"altitudeRate":{"type":"number","description":"d(true altitude)/dt at the crossing, degrees per minute (±10 s symmetric difference)."},"sun":{"type":"object","properties":{"azimuth":{"type":"number"},"altitude":{"type":"number","description":"Sun centre true (vacuum) altitude, degrees, seen from this point (twilight thresholds use this)."},"apparentAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refracted, down to the sea horizon at the eye's height; null below it, as /v1/position."}},"required":["azimuth","altitude","apparentAltitude"],"additionalProperties":false,"description":"include=sun: the Sun seen from this point at this instant."},"phase":{"type":"object","properties":{"phaseAngle":{"type":"number"},"illuminatedFraction":{"type":"number"},"elongation":{"type":"number"},"brightLimbAngle":{"type":"number"},"name":{"type":"string","enum":["new","waxing crescent","first quarter","waxing gibbous","full","waning gibbous","last quarter","waning crescent"]}},"required":["phaseAngle","illuminatedFraction","elongation","brightLimbAngle","name"],"additionalProperties":false,"description":"include=phase: the Moon's geocentric phase at this instant, as /v1/position."},"aimOffset":{"type":"number","description":"With aim: angular distance from the disc centre to the aim point, degrees (the angular radius for a limb)."},"aimAngle":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"With aim: direction centre → aim point, degrees clockwise from the local vertical as the observer sees it (0 = upper limb, 180 = lower; litCentroid = the bright limb's direction)."}},"required":["time","direction","azimuth","altitude","altitudeRate"],"additionalProperties":false}},"conventions":{"type":"object","properties":{"definition":{"type":"string"},"aim":{"type":"object","properties":{"point":{"type":"string","enum":["center","upper","lower","litCentroid"]},"definition":{"type":"string"}},"required":["point","definition"],"additionalProperties":false},"altitudeType":{"type":"string","enum":["true","apparent","profile"]},"trueLimbAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"True altitude of the chosen limb at the crossing (null for a profile)."},"refraction":{"anyOf":[{"type":"object","properties":{"model":{"type":"string"},"temperatureC":{"type":"number"},"pressureHpa":{"type":"number"}},"required":["model","temperatureC","pressureHpa"],"additionalProperties":false},{"type":"null"}]},"horizon":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["sea","geometric","custom","profile"]},"altitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Apparent altitude of the horizon, degrees (null for a profile)."},"dip":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sea-horizon dip, degrees: √(1 − k)·acos(R/(R + heightMsl)), k = terrestrialRefractionK, R = 6 371 008.8 m."},"terrestrialRefractionK":{"type":"number"},"profile":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"azimuth":{"type":"number"},"elevation":{"type":"number"}},"required":["azimuth","elevation"],"additionalProperties":false}},{"type":"null"}]}},"required":["kind","altitude","dip","terrestrialRefractionK","profile"],"additionalProperties":false},{"type":"null"}]},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false},"include":{"type":"string"}},"required":["definition","aim","altitudeType","trueLimbAltitude","refraction","horizon","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["body","start","end","observer","crossings","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/alignment":{"get":{"tags":["sky"],"operationId":"sky.alignment","parameters":[{"name":"body","in":"query","schema":{"type":"string","enum":["sun","moon"]},"required":true},{"name":"targetLat","in":"query","schema":{"type":"string"},"required":true},{"name":"targetLon","in":"query","schema":{"type":"string"},"required":true},{"name":"targetHeight","in":"query","schema":{"type":"string"},"required":true},{"name":"targetHeightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"start","in":"query","schema":{"type":"string"},"required":true},{"name":"end","in":"query","schema":{"type":"string"},"required":true},{"name":"stepSeconds","in":"query","schema":{"type":"string"},"required":false},{"name":"maxDistanceKm","in":"query","schema":{"type":"string"},"required":false},{"name":"temperature","in":"query","schema":{"type":"string"},"required":false},{"name":"pressure","in":"query","schema":{"type":"string"},"required":false},{"name":"dut1","in":"query","schema":{"type":"string"},"required":false},{"name":"lat","in":"query","schema":{"type":"string"},"required":false},{"name":"lon","in":"query","schema":{"type":"string"},"required":false},{"name":"include","in":"query","schema":{"type":"string"},"required":false},{"name":"aim","in":"query","schema":{"type":"string","enum":["center","upper","lower","litCentroid"]},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","enum":["sun","moon"]},"target":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false,"description":"The target point with its height in both references (heightRef: what targetHeight was measured from)."},"track":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"distanceKm":{"type":"number"},"azimuth":{"type":"number","description":"The body's azimuth seen from this standing point, degrees true; by construction = the forward geodesic azimuth from here to the target (conventions.azimuth)."},"apparentAltitude":{"type":"number","description":"The body's apparent altitude seen from here = the target's apparent elevation (terrestrial refraction k·θ/2 included), degrees."},"angularRadius":{"type":"number"},"altitudeRate":{"type":"number","description":"d(true altitude)/dt of the body seen from this standing point, degrees per minute (±10 s symmetric difference, as /v1/position)."},"azimuthRate":{"type":"number","description":"d(azimuth)/dt of the body seen from this standing point, degrees per minute (±10 s symmetric difference, as /v1/position)."},"heightEllipsoid":{"type":"number","description":"The eye's height above WGS-84 at this standing point, metres."},"heightMsl":{"type":"number","description":"The eye's height above the EGM96 geoid at this standing point, metres."},"geoidUndulation":{"type":"number","description":"EGM96 N at this standing point, metres: heightEllipsoid = heightMsl + geoidUndulation."},"sun":{"type":"object","properties":{"azimuth":{"type":"number"},"altitude":{"type":"number","description":"Sun centre true (vacuum) altitude, degrees, seen from this point (twilight thresholds use this)."},"apparentAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refracted, down to the sea horizon at the eye's height; null below it, as /v1/position."}},"required":["azimuth","altitude","apparentAltitude"],"additionalProperties":false,"description":"include=sun: the Sun seen from this point at this instant."},"phase":{"type":"object","properties":{"phaseAngle":{"type":"number"},"illuminatedFraction":{"type":"number"},"elongation":{"type":"number"},"brightLimbAngle":{"type":"number"},"name":{"type":"string","enum":["new","waxing crescent","first quarter","waxing gibbous","full","waning gibbous","last quarter","waning crescent"]}},"required":["phaseAngle","illuminatedFraction","elongation","brightLimbAngle","name"],"additionalProperties":false,"description":"include=phase: the Moon's geocentric phase at this instant, as /v1/position."},"aimOffset":{"type":"number","description":"With aim: angular distance from the disc centre to the aim point, degrees (the angular radius for a limb)."},"aimAngle":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"With aim: direction centre → aim point, degrees clockwise from the local vertical as the observer sees it (0 = upper limb, 180 = lower; litCentroid = the bright limb's direction)."}},"required":["time","lat","lon","distanceKm","azimuth","apparentAltitude","angularRadius","altitudeRate","azimuthRate","heightEllipsoid","heightMsl","geoidUndulation"],"additionalProperties":false}},"fromObserver":{"type":"object","properties":{"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"azimuthToTarget":{"type":"number"},"distanceKm":{"type":"number"},"targetElevation":{"type":"number"},"passes":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"altitudeOffset":{"type":"number"},"angularRadius":{"type":"number"},"apparentAltitude":{"type":"number"},"sun":{"type":"object","properties":{"azimuth":{"type":"number"},"altitude":{"type":"number","description":"Sun centre true (vacuum) altitude, degrees, seen from this point (twilight thresholds use this)."},"apparentAltitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refracted, down to the sea horizon at the eye's height; null below it, as /v1/position."}},"required":["azimuth","altitude","apparentAltitude"],"additionalProperties":false,"description":"include=sun: the Sun seen from this point at this instant."},"phase":{"type":"object","properties":{"phaseAngle":{"type":"number"},"illuminatedFraction":{"type":"number"},"elongation":{"type":"number"},"brightLimbAngle":{"type":"number"},"name":{"type":"string","enum":["new","waxing crescent","first quarter","waxing gibbous","full","waning gibbous","last quarter","waning crescent"]}},"required":["phaseAngle","illuminatedFraction","elongation","brightLimbAngle","name"],"additionalProperties":false,"description":"include=phase: the Moon's geocentric phase at this instant, as /v1/position."}},"required":["time","altitudeOffset","angularRadius","apparentAltitude"],"additionalProperties":false}}},"required":["observer","azimuthToTarget","distanceKm","targetElevation","passes"],"additionalProperties":false},"conventions":{"type":"object","properties":{"definition":{"type":"string"},"azimuth":{"type":"string"},"apparentAltitude":{"type":"string"},"terrestrialRefraction":{"type":"string","description":"Whether and how refraction along the sight line (eye → target) is modelled."},"heights":{"type":"string"},"rates":{"type":"string"},"include":{"type":"string"},"aim":{"type":"object","properties":{"point":{"type":"string","enum":["center","upper","lower","litCentroid"]},"definition":{"type":"string"}},"required":["point","definition"],"additionalProperties":false},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What height was measured from; default = no height, the eye is on the geoid."},"targetHeightRef":{"type":"string","enum":["ellipsoid","msl"]},"terrestrialRefractionK":{"type":"number"},"refraction":{"type":"object","properties":{"model":{"type":"string"},"temperatureC":{"type":"number"},"pressureHpa":{"type":"number"}},"required":["model","temperatureC","pressureHpa"],"additionalProperties":false},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false}},"required":["definition","azimuth","apparentAltitude","terrestrialRefraction","heights","rates","heightRef","targetHeightRef","terrestrialRefractionK","refraction","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["body","target","track","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/sightline":{"get":{"tags":["sky"],"operationId":"sky.sightline","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"targetLat","in":"query","schema":{"type":"string"},"required":true},{"name":"targetLon","in":"query","schema":{"type":"string"},"required":true},{"name":"targetHeight","in":"query","schema":{"type":"string"},"required":true},{"name":"targetHeightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"samples","in":"query","schema":{"type":"string"},"required":false},{"name":"obstacles","in":"query","schema":{"type":"string"},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"target":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"distanceKm":{"type":"number"},"azimuth":{"type":"number","description":"Forward geodesic azimuth observer → target."},"samples":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"profile":{"type":"array","items":{"type":"object","properties":{"distanceKm":{"type":"number","description":"Geodesic ground distance from the observer to the foot of this point."},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"heightMsl":{"type":"number","description":"The straight (unrefracted) sight line's height above the EGM96 geoid here, metres; Earth's curvature included."},"refractedHeightMsl":{"type":"number","description":"The refracted ray's height here (terrestrial refraction k = 0.13): heightMsl + k·s₁·s₂/(2R)."},"heightEllipsoid":{"type":"number","description":"The straight line's WGS-84 geodetic height here, metres."},"geoidUndulation":{"type":"number","description":"EGM96 N at the foot: heightEllipsoid = heightMsl + geoidUndulation."}},"required":["distanceKm","lat","lon","heightMsl","refractedHeightMsl","heightEllipsoid","geoidUndulation"],"additionalProperties":false}},"obstacles":{"type":"array","items":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"heightMsl":{"type":"number"},"distanceKm":{"type":"number","description":"Along the line from the observer (projection)."},"crossTrackM":{"type":"number","description":"Offset from the line, metres, positive to the right looking at the target."},"lineHeightMsl":{"anyOf":[{"type":"number"},{"type":"null"}]},"refractedLineHeightMsl":{"anyOf":[{"type":"number"},{"type":"null"}]},"clearanceM":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Straight line − obstacle height, metres; negative = the obstacle is above the line. Null when not between the ends."},"refractedClearanceM":{"anyOf":[{"type":"number"},{"type":"null"}]},"blocks":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"refractedClearanceM < 0."}},"required":["lat","lon","heightMsl","distanceKm","crossTrackM","lineHeightMsl","refractedLineHeightMsl","clearanceM","refractedClearanceM","blocks"],"additionalProperties":false}},"conventions":{"type":"object","properties":{"definition":{"type":"string"},"terrestrialRefraction":{"type":"string"},"obstacles":{"type":"string"},"heights":{"type":"string"},"terrestrialRefractionK":{"type":"number"},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false}},"required":["definition","terrestrialRefraction","obstacles","heights","terrestrialRefractionK","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["observer","target","distanceKm","azimuth","samples","profile","obstacles","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/track":{"get":{"tags":["sky"],"operationId":"sky.track","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"start","in":"query","schema":{"type":"string"},"required":true},{"name":"end","in":"query","schema":{"type":"string"},"required":true},{"name":"stepSeconds","in":"query","schema":{"type":"string"},"required":false},{"name":"temperature","in":"query","schema":{"type":"string"},"required":false},{"name":"pressure","in":"query","schema":{"type":"string"},"required":false},{"name":"horizon","in":"query","schema":{"anyOf":[{"type":"string","enum":["sea","geometric"]},{"type":"string"}]},"required":false},{"name":"dut1","in":"query","schema":{"type":"string"},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"stepSeconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Samples: sample i is at start + i·stepSeconds; (end − start)/stepSeconds + 1."},"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"sun":{"type":"object","properties":{"azimuth":{"type":"array","items":{"type":"number"},"description":"Degrees from north through east, [0, 360), one per sample."},"altitude":{"type":"array","items":{"type":"number"},"description":"True (vacuum) altitude, degrees."},"apparentAltitude":{"type":"array","items":{"anyOf":[{"type":"number"},{"type":"null"}]},"description":"Refracted altitude, degrees; null below the observer's horizon or the refraction model's floor, exactly as /v1/position."}},"required":["azimuth","altitude","apparentAltitude"],"additionalProperties":false},"moon":{"type":"object","properties":{"azimuth":{"type":"array","items":{"type":"number"},"description":"Degrees from north through east, [0, 360), one per sample."},"altitude":{"type":"array","items":{"type":"number"},"description":"True (vacuum) altitude, degrees."},"apparentAltitude":{"type":"array","items":{"anyOf":[{"type":"number"},{"type":"null"}]},"description":"Refracted altitude, degrees; null below the observer's horizon or the refraction model's floor, exactly as /v1/position."}},"required":["azimuth","altitude","apparentAltitude"],"additionalProperties":false},"conventions":{"type":"object","properties":{"refraction":{"type":"object","properties":{"model":{"type":"string"},"temperatureC":{"type":"number"},"pressureHpa":{"type":"number"},"validFrom":{"type":"number","description":"Lowest apparent altitude that gets a value: max(horizon, the model floor −1.6963°). Below it apparentAltitude is null."},"validTo":{"type":"number"},"uncertainty":{"type":"string"}},"required":["model","temperatureC","pressureHpa","validFrom","validTo","uncertainty"],"additionalProperties":false},"horizon":{"type":"object","properties":{"kind":{"type":"string","enum":["sea","geometric","custom","profile"]},"altitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Apparent altitude of the horizon, degrees (null for a profile)."},"dip":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sea-horizon dip, degrees: √(1 − k)·acos(R/(R + heightMsl)), k = terrestrialRefractionK, R = 6 371 008.8 m."},"terrestrialRefractionK":{"type":"number"},"profile":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"azimuth":{"type":"number"},"elevation":{"type":"number"}},"required":["azimuth","elevation"],"additionalProperties":false}},{"type":"null"}]}},"required":["kind","altitude","dip","terrestrialRefractionK","profile"],"additionalProperties":false},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false}},"required":["refraction","horizon","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["start","end","stepSeconds","count","observer","sun","moon","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/alignment/search":{"post":{"tags":["search"],"operationId":"search.search","parameters":[],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","enum":["sun","moon"]},"start":{"type":"string"},"end":{"type":"string"},"target":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"observer":{"type":"object","properties":{"height":{"type":"number","description":"The eye's height as given (0 with heightRef default when omitted: the eye on the geoid)."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"]}},"required":["height","heightRef"],"additionalProperties":false},"region":{"type":"object","properties":{"encoding":{"type":"string","description":"Canonical r1 encoding: the cache key part for the region (window GETs carry it)."},"polygons":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rings":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vertices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bbox":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"maxItems":4,"minItems":4},"geoidUndulation":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false,"description":"EGM96 N over the region's vertices, metres."}},"required":["encoding","polygons","rings","vertices","bbox","geoidUndulation"],"additionalProperties":false},"passes":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","description":"Midpoint of the pass's first entry and last exit; standingPoint and the body's and Sun's values are at this instant."},"segments":{"type":"array","items":{"type":"object","properties":{"enter":{"type":"object","properties":{"time":{"type":"string"},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}},"required":["time","lat","lon"],"additionalProperties":false,"description":"Where and when the standing point crosses into the region (a point on a region edge)."},"exit":{"type":"object","properties":{"time":{"type":"string"},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}},"required":["time","lat","lon"],"additionalProperties":false}},"required":["enter","exit"],"additionalProperties":false},"description":"Each in-region interval of the ground track, in time order (piers and inlets split a pass)."},"standingPoint":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"distanceKm":{"type":"number"}},"required":["lat","lon","distanceKm"],"additionalProperties":false,"description":"The alignment standing point at `time` (may lie between segments, outside the region); distanceKm to the target."},"azimuth":{"type":"number","description":"The body's (aim point's) azimuth from the standing point, degrees true = the bearing to the target."},"apparentAltitude":{"type":"number","description":"The body's (aim point's) apparent altitude from the standing point = the target's apparent elevation, degrees."},"angularRadius":{"type":"number"},"illuminatedFraction":{"type":"number","description":"The Moon's illuminated fraction, 0–1 (geocentric, as /v1/position), whichever the body (minIlluminated filters on it)."},"sunAltitude":{"type":"number","description":"The Sun centre's true altitude from the standing point, degrees (twilight convention −6/−12/−18; maxSunAltitude filters on it)."},"sun":{"type":"object","properties":{"azimuth":{"type":"number"},"altitude":{"type":"number"},"apparentAltitude":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["azimuth","altitude","apparentAltitude"],"additionalProperties":false},"phase":{"type":"object","properties":{"phaseAngle":{"type":"number"},"illuminatedFraction":{"type":"number"},"elongation":{"type":"number"},"brightLimbAngle":{"type":"number"},"name":{"type":"string","enum":["new","waxing crescent","first quarter","waxing gibbous","full","waning gibbous","last quarter","waning crescent"]}},"required":["phaseAngle","illuminatedFraction","elongation","brightLimbAngle","name"],"additionalProperties":false}},"required":["time","segments","standingPoint","azimuth","apparentAltitude","angularRadius","illuminatedFraction","sunAltitude"],"additionalProperties":false},"description":"Passes whose first entry lies in [start, end) and that pass the filters, in time order."},"search":{"type":"object","properties":{"geometry":{"type":"object","properties":{"reference":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}},"required":["lat","lon"],"additionalProperties":false,"description":"The region's bbox centre, where the scan looks at the body."},"distanceM":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false,"description":"Nearest and farthest region points from the target, metres (exact WGS-84 geodesics)."},"elevation":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false,"description":"The target's apparent elevation over the whole region at the eye height, degrees: the band the body's apparent altitude must be in."},"azimuth":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false,"description":"Forward azimuths from the region to the target, degrees true."},"band":{"type":"object","properties":{"trueAltitudeMin":{"type":"number"},"trueAltitudeMax":{"type":"number"},"azimuthMin":{"type":"number"},"azimuthMax":{"type":"number"}},"required":["trueAltitudeMin","trueAltitudeMax","azimuthMin","azimuthMax"],"additionalProperties":false,"description":"The same band for the body seen from the reference point, as true altitude, margins included."},"margins":{"type":"object","properties":{"altitude":{"type":"number"},"azimuth":{"type":"number"}},"required":["altitude","azimuth"],"additionalProperties":false},"maxDistanceKm":{"type":"number"},"referenceSpreadM":{"type":"number"}},"required":["reference","distanceM","elevation","azimuth","band","margins","maxDistanceKm","referenceSpreadM"],"additionalProperties":false},"windows":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"passes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cache":{"type":"string","description":"Workers Caching status of this window's GET (HIT, MISS, …; LOCAL when computed in-process)."}},"required":["start","end","passes","cache"],"additionalProperties":false}},"passesBeforeFilters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counters":{"type":"object","additionalProperties":{"type":"number"},"description":"Summed over the windows computed for this answer (cache hits report the counts of the run that filled them)."}},"required":["geometry","windows","passesBeforeFilters","counters"],"additionalProperties":false},"conventions":{"type":"object","properties":{"definition":{"type":"string"},"region":{"type":"string"},"segments":{"type":"string"},"passes":{"type":"string"},"candidates":{"type":"string"},"windows":{"type":"string"},"filters":{"type":"string"},"azimuth":{"type":"string"},"terrestrialRefraction":{"type":"string"},"heights":{"type":"string"},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"]},"targetHeightRef":{"type":"string","enum":["ellipsoid","msl"]},"terrestrialRefractionK":{"type":"number"},"refraction":{"type":"object","properties":{"model":{"type":"string"},"temperatureC":{"type":"number"},"pressureHpa":{"type":"number"}},"required":["model","temperatureC","pressureHpa"],"additionalProperties":false},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false},"aim":{"type":"object","properties":{"point":{"type":"string","enum":["center","upper","lower","litCentroid"]},"definition":{"type":"string"}},"required":["point","definition"],"additionalProperties":false}},"required":["definition","region","segments","passes","candidates","windows","filters","azimuth","terrestrialRefraction","heights","heightRef","targetHeightRef","terrestrialRefractionK","refraction","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["body","start","end","target","observer","region","passes","search","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","enum":["sun","moon"]},"targetLat":{"type":"number","minimum":-90,"maximum":90},"targetLon":{"type":"number","minimum":-180,"maximum":180},"targetHeight":{"type":"number","minimum":-500,"maximum":100000,"description":"Height of the point to frame (e.g. the figure's middle), metres; see targetHeightRef."},"targetHeightRef":{"type":"string","enum":["ellipsoid","msl"],"description":"What targetHeight is measured from: ellipsoid (default) or msl (EGM96)."},"region":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"description":"[lon, lat] in degrees (a third element, altitude, is ignored)."}}},"bbox":{"type":"array","items":{"type":"number"}}},"required":["type","coordinates"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"description":"[lon, lat] in degrees (a third element, altitude, is ignored)."}}}},"bbox":{"type":"array","items":{"type":"number"}}},"required":["type","coordinates"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"geometry":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"description":"[lon, lat] in degrees (a third element, altitude, is ignored)."}}},"bbox":{"type":"array","items":{"type":"number"}}},"required":["type","coordinates"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"description":"[lon, lat] in degrees (a third element, altitude, is ignored)."}}}},"bbox":{"type":"array","items":{"type":"number"}}},"required":["type","coordinates"],"additionalProperties":false}]},"properties":{"anyOf":[{},{"type":"null"}]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"bbox":{"type":"array","items":{"type":"number"}}},"required":["type","geometry"],"additionalProperties":false},{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"maxItems":4,"minItems":4,"description":"[west, south, east, north], degrees (RFC 7946 bbox order); no antimeridian crossing."}],"description":"Where you can stand: a GeoJSON Polygon or MultiPolygon (holes allowed; a Feature wrapping one is accepted) or a bbox. Edges are straight lines in (lon, lat) (RFC 7946 §3.1.1); insideness is even-odd per polygon. At most 1 000 vertices and 100 rings, ≤ 50 km across, ≤ 100 km from the target and not containing it. Coordinates are quantised to 1e-7° (≤ 1.1 cm)."},"height":{"type":"number","minimum":-500,"maximum":100000,"description":"Eye height wherever you stand, metres; see heightRef. Default: the eye on the geoid (heightMsl 0)."},"heightRef":{"type":"string","enum":["ellipsoid","msl"],"description":"What height is measured from: ellipsoid (default) or msl, in which case the eye is height + N(P) at every standing point P."},"start":{"type":"string"},"end":{"type":"string","description":"Passes whose first entry lies in [start, end); at most 400 days."},"temperature":{"type":"number","minimum":-90,"maximum":60},"pressure":{"type":"number","minimum":0,"maximum":1100},"dut1":{"type":"number","minimum":-0.9,"maximum":0.9},"aim":{"type":"string","enum":["center","upper","lower","litCentroid"],"description":"Which point of the disc sits on the target (as /v1/alignment): center (default), upper, lower, litCentroid (Moon)."},"include":{"type":"string","description":"Extra context per pass, as on every endpoint: sun (azimuth, true and apparent altitude), phase (the Moon's phase block), or sun,phase."},"minIlluminated":{"type":"number","minimum":0,"maximum":1,"description":"Keep passes whose Moon illuminated fraction (at the pass time) is at least this, 0–1."},"maxSunAltitude":{"type":"number","minimum":-90,"maximum":90,"description":"Keep passes whose Sun centre true altitude (at the pass time, from the standing point) is at most this, degrees; e.g. −4 for a dark sky."}},"required":["body","targetLat","targetLon","targetHeight","region","start","end"],"additionalProperties":false}}},"required":true}}},"/v1/magnetic":{"get":{"tags":["earth"],"operationId":"earth.magnetic","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"height","in":"query","schema":{"type":"string"},"required":false},{"name":"heightRef","in":"query","schema":{"type":"string","enum":["ellipsoid","msl"]},"required":false},{"name":"time","in":"query","schema":{"type":"string"},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"time":{"type":"string"},"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"height":{"type":"number","description":"Metres above the WGS-84 ellipsoid (same as heightEllipsoid; kept for compatibility)."},"heightEllipsoid":{"type":"number"},"heightMsl":{"type":"number","description":"Metres above the EGM96 geoid (≈ mean sea level)."},"geoidUndulation":{"type":"number","description":"EGM96 N, metres: heightEllipsoid = heightMsl + geoidUndulation."},"heightRef":{"type":"string","enum":["ellipsoid","msl","default"],"description":"What the request's height was measured from; default = no height given, the observer is on the geoid."}},"required":["lat","lon","height","heightEllipsoid","heightMsl","geoidUndulation","heightRef"],"additionalProperties":false},"magnetic":{"type":"object","properties":{"model":{"type":"string","enum":["WMM2025"]},"declination":{"type":"number","description":"Magnetic declination, degrees, east positive. Magnetic bearing = true bearing − declination."},"inclination":{"type":"number","description":"Dip, degrees, down positive."},"horizontalIntensityNt":{"type":"number"},"totalIntensityNt":{"type":"number"},"decimalYear":{"type":"number"},"inValidityWindow":{"type":"boolean","description":"WMM2025 is valid 2025.0–2030.0; outside it the secular variation is extrapolated."},"compass":{"type":"string","enum":["ok","caution","blackout"],"description":"WMM2025's compass zones by horizontal intensity H: blackout (H < 2000 nT, around the dip poles: the declination is unreliable and a compass does not work), caution (2000 ≤ H < 6000 nT: degraded), ok."}},"required":["model","declination","inclination","horizontalIntensityNt","totalIntensityNt","decimalYear","inValidityWindow","compass"],"additionalProperties":false},"conventions":{"type":"object","properties":{"model":{"type":"string"},"declination":{"type":"string"},"compass":{"type":"string"},"height":{"type":"string"},"geoid":{"type":"object","properties":{"model":{"type":"string","enum":["EGM96"]},"source":{"type":"string"},"interpolationErrorM":{"type":"object","properties":{"rms":{"type":"number"},"p99":{"type":"number"},"max":{"type":"number"}},"required":["rms","p99","max"],"additionalProperties":false}},"required":["model","source","interpolationErrorM"],"additionalProperties":false}},"required":["model","declination","compass","height","geoid"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["time","observer","magnetic","conventions","provenance"],"additionalProperties":false}}}},"400":{"description":"InvalidRequest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidRequestEncoded"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/v1/weather":{"get":{"tags":["earth"],"operationId":"earth.weather","parameters":[{"name":"lat","in":"query","schema":{"type":"string"},"required":true},{"name":"lon","in":"query","schema":{"type":"string"},"required":true},{"name":"count","in":"query","schema":{"type":"string"},"required":false}],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"time":{"type":"string"},"observer":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"magneticDeclination":{"type":"number","description":"WMM2025 at the observer, height 0, now; east positive. Full precision (was rounded to 0.01° before 2026-10-29): the same value /v1/magnetic gives for lat/lon now."}},"required":["lat","lon","magneticDeclination"],"additionalProperties":false},"stations":{"type":"array","items":{"type":"object","properties":{"stationId":{"type":"string"},"raw":{"type":"string","description":"The METAR exactly as reported (raw_text)."},"metarType":{"anyOf":[{"type":"string"},{"type":"null"}]},"flightCategory":{"anyOf":[{"type":"string"},{"type":"null"}]},"observationTime":{"type":"string"},"observationAgeSeconds":{"type":"number","description":"now − observation_time."},"observationStale":{"type":"boolean","description":"Observation older than 75 minutes (METARs are hourly)."},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"elevationM":{"anyOf":[{"type":"number"},{"type":"null"}]},"distanceKm":{"type":"number","description":"Great-circle distance from the observer (sphere of radius 6 371.0088 km)."},"bearing":{"type":"object","properties":{"true":{"type":"number","description":"Initial great-circle bearing from the observer to the station, degrees true, [0, 360)."},"magnetic":{"type":"number","description":"The same bearing, degrees magnetic (true − WMM2025 declination at the observer)."}},"required":["true","magnetic"],"additionalProperties":false},"temperatureC":{"anyOf":[{"type":"number"},{"type":"null"}]},"dewpointC":{"anyOf":[{"type":"number"},{"type":"null"}]},"wind":{"type":"object","properties":{"directionDegTrue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Direction the wind blows from, degrees true; null when calm or variable."},"variable":{"type":"boolean"},"calm":{"type":"boolean"},"speedKt":{"anyOf":[{"type":"number"},{"type":"null"}]},"gustKt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["directionDegTrue","variable","calm","speedKt","gustKt"],"additionalProperties":false},"visibility":{"type":"object","properties":{"statuteMiles":{"anyOf":[{"type":"number"},{"type":"null"}]},"orMore":{"type":"boolean","description":"Reported as N+ (e.g. 10+): at least N."}},"required":["statuteMiles","orMore"],"additionalProperties":false},"altimeterInHg":{"anyOf":[{"type":"number"},{"type":"null"}]},"altimeterHpa":{"anyOf":[{"type":"number"},{"type":"null"}]},"seaLevelPressureHpa":{"anyOf":[{"type":"number"},{"type":"null"}]},"wx":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Present weather (wx_string), e.g. -RA BR."},"sky":{"type":"array","items":{"type":"object","properties":{"cover":{"type":"string"},"baseFtAgl":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["cover","baseFtAgl"],"additionalProperties":false}},"verticalVisibilityFt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["stationId","raw","metarType","flightCategory","observationTime","observationAgeSeconds","observationStale","lat","lon","elevationM","distanceKm","bearing","temperatureC","dewpointC","wind","visibility","altimeterInHg","altimeterHpa","seaLevelPressureHpa","wx","sky","verticalVisibilityFt"],"additionalProperties":false}},"feed":{"type":"object","properties":{"source":{"type":"string"},"fetchedAt":{"type":"string","description":"When this Worker last confirmed the feed with aviationweather.gov (200 or 304)."},"ageSeconds":{"type":"number","description":"now − fetchedAt."},"lastModified":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Upstream Last-Modified of the file."},"upstreamAgeSeconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"now − lastModified."},"stale":{"type":"boolean","description":"Older than the 60 s fresh window (served while a refresh runs, or because upstream failed)."},"tier":{"type":"string","enum":["hit","miss","expired","stale","updating","revalidated","bypass","dynamic","none","stale-on-error"],"description":"Workers Caching status of the feed fetch, lower-cased cf-cache-status (hit, updating = served stale while it refreshes, miss/expired = fetched from aviationweather.gov, revalidated = 304 from upstream); stale-on-error = the feed fetch failed and this isolate's last copy answered; none = no cache (dev)."},"stations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","fetchedAt","ageSeconds","lastModified","upstreamAgeSeconds","stale","tier","stations"],"additionalProperties":false},"conventions":{"type":"object","properties":{"definition":{"type":"string"},"distance":{"type":"string"},"bearing":{"type":"string"},"magneticDeclination":{"type":"string"}},"required":["definition","distance","bearing","magneticDeclination"],"additionalProperties":false},"provenance":{"type":"object","properties":{"implementation":{"type":"string"},"version":{"type":"string"},"sources":{"type":"array","items":{"type":"string"},"description":"The data and models this answer comes from (ephemeris, geoid, field model, feed), with versions."},"diagnostics":{"type":"object","properties":{"blocks":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"computeMs":{"type":"number"},"cache":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["blocks","computeMs"],"additionalProperties":false}},"required":["implementation","version","sources"],"additionalProperties":false}},"required":["time","observer","stations","feed","conventions","provenance"],"additionalProperties":false}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnavailableEncoded"}}}}}}},"/healthz":{"get":{"tags":["meta"],"operationId":"meta.health","parameters":[],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"implementation":{"type":"string"},"version":{"type":"string"}},"required":["ok","implementation","version"],"additionalProperties":false}}}}}}}},"components":{"schemas":{"UnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unavailable"]},"message":{"type":"string"}},"required":["_tag","message"],"additionalProperties":false},"InvalidRequestEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["InvalidRequest"]},"message":{"type":"string"},"parameter":{"type":"string"},"allowed":{"type":"array","items":{"type":"string"}}},"required":["_tag","message"],"additionalProperties":false}},"securitySchemes":{}},"security":[],"tags":[{"name":"sky"},{"name":"search"},{"name":"earth"},{"name":"meta"}]}