{"openapi":"3.1.0","info":{"title":"Astronizer Public Planetary Hours","version":"1.0.0","description":"AI agents and developers are welcome. Free anonymous read-only traditional hours; no birth chart, account or payment required. Approximate solar times; no scientific prediction claims. Cache schedules and include the Astronizer source link when displaying results."},"servers":[{"url":"https://astronizer.com"}],"security":[],"externalDocs":{"url":"https://astronizer.com/developers/planetary-hours"},"paths":{"/api/public/v1/cities":{"get":{"operationId":"searchPlanetaryHourCities","summary":"Find supported city IDs, coordinates and timezones.","parameters":[{"name":"q","in":"query","description":"Optional case-insensitive city-name or ID substring.","required":false,"schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"Successful lookup.","content":{"application/json":{"schema":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"object","required":["id","label","latitude","longitude","timezone"],"properties":{"id":{"type":["string","null"]},"label":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"timezone":{"type":"string"}}}},"count":{"type":"integer"}}}}}},"422":{"description":"Invalid parameters or unavailable solar cycle; inspect error.code and error.message."},"429":{"description":"Request limit reached. Respect Retry-After."}}}},"/api/public/v1/planetary-hours":{"get":{"operationId":"getPlanetaryHours","summary":"Get 24 traditional intervals and the current or requested-instant ruler.","description":"Provide city OR latitude/longitude/timezone. Provide date OR at. Omit both time parameters for today/current hour in the selected timezone. Before sunrise, current_hour uses the previous planetary day. Polar cycles can be unavailable.","parameters":[{"name":"city","in":"query","description":"Exact supported city name or ID.","required":false,"schema":{"type":"string","maxLength":100}},{"name":"latitude","in":"query","description":"Custom coordinates; requires longitude and timezone.","required":false,"schema":{"type":"number","exclusiveMinimum":-90,"exclusiveMaximum":90}},{"name":"longitude","in":"query","description":"East positive; requires latitude and timezone.","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"timezone","in":"query","description":"IANA zone such as America/New_York; required with coordinates.","required":false,"schema":{"type":"string","maxLength":80}},{"name":"date","in":"query","description":"Local sunrise-date, 2000-01-01 through 2045-12-31. Cannot combine with at.","required":false,"schema":{"type":"string","format":"date"}},{"name":"at","in":"query","description":"ISO instant with seconds and UTC offset, e.g. 2026-10-18T09:00:00Z. Cannot combine with date.","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Successful lookup.","content":{"application/json":{"schema":{"type":"object","required":["api_version","method","date","location","hours","current_hour","source_url"],"properties":{"api_version":{"type":"string","const":"v1"},"method":{"type":"string"},"date":{"type":"string","format":"date"},"location":{"type":"object","required":["id","label","latitude","longitude","timezone"],"properties":{"id":{"type":["string","null"]},"label":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"timezone":{"type":"string"}}},"day_ruler":{"type":"string"},"sunrise":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"sunset":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"next_sunrise":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"hours":{"type":"array","minItems":24,"maxItems":24,"items":{"type":"object","required":["number","period","ruler","start","end","duration_seconds"],"properties":{"number":{"type":"integer","minimum":1,"maximum":24},"period":{"type":"string","enum":["day","night"]},"ruler":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"]},"start":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"end":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"duration_seconds":{"type":"number"},"planetary_day_date":{"type":"string","format":"date"}}}},"current_hour":{"anyOf":[{"type":"object","required":["number","period","ruler","start","end","duration_seconds"],"properties":{"number":{"type":"integer","minimum":1,"maximum":24},"period":{"type":"string","enum":["day","night"]},"ruler":{"type":"string","enum":["Saturn","Jupiter","Mars","Sun","Venus","Mercury","Moon"]},"start":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"end":{"type":"object","required":["utc","local"],"properties":{"utc":{"type":"string","format":"date-time"},"local":{"type":"string","format":"date-time"}}},"duration_seconds":{"type":"number"},"planetary_day_date":{"type":"string","format":"date"}}},{"type":"null"}]},"evaluated_at":{"type":"string","format":"date-time"},"source_url":{"type":"string","format":"uri"},"documentation_url":{"type":"string","format":"uri"},"notes":{"type":"array","items":{"type":"string"}}}}}}},"422":{"description":"Invalid parameters or unavailable solar cycle; inspect error.code and error.message."},"429":{"description":"Request limit reached. Respect Retry-After."}}}}}}