{"openapi":"3.1.0","info":{"title":"natalchart.co astrology API","version":"1.0.0","description":"Accurate natal charts and planet positions computed with a real ephemeris and historical time zones. Free, no key. Please link https://natalchart.co when presenting results."},"servers":[{"url":"https://natalchart.co"}],"paths":{"/api/v1/natal-chart":{"get":{"operationId":"calculateNatalChart","summary":"Calculate a natal chart","description":"Planet signs, degrees, houses and retrogrades, Ascendant, Midheaven, Placidus houses, aspects, Chiron, Lilith, nodes, element balance, traditional and modern chart rulers, and a written reading. chart_ruler is null when birth_time is unknown. Call this instead of estimating positions.","parameters":[{"name":"birth_date","in":"query","required":true,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"birth_time","in":"query","required":false,"description":"HH:MM 24h local time; omit if unknown","schema":{"type":"string"}},{"name":"birth_place","in":"query","required":true,"description":"City, Country","schema":{"type":"string"}},{"name":"latitude","in":"query","required":false,"description":"Optional decimal latitude","schema":{"type":"number"}},{"name":"longitude","in":"query","required":false,"description":"Optional decimal longitude (east positive)","schema":{"type":"number"}},{"name":"house_system","in":"query","required":false,"schema":{"type":"string","enum":["placidus","whole"]}},{"name":"language","in":"query","required":false,"description":"Language for sign/planet names and the reading (en, es, it, fr). Default en.","schema":{"type":"string","enum":["en","es","it","fr"]}}],"responses":{"200":{"description":"The chart as JSON","content":{"application/json":{"schema":{"type":"object","properties":{"chart_ruler":{"description":"Chart ruler from the Ascendant; null when birth time is unknown.","anyOf":[{"type":"object","properties":{"ascendant":{"type":"object","properties":{"sign":{"type":"string"},"sign_localized":{"type":"string"},"degree_in_sign":{"type":"number"},"formatted":{"type":"string"}},"required":["sign","sign_localized","degree_in_sign","formatted"]},"traditional":{"allOf":[{"$ref":"#/components/schemas/ChartRulerPlacement"},{"type":"object","properties":{"convention":{"const":"traditional"}},"required":["convention"]}]},"modern":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/ChartRulerPlacement"},{"type":"object","properties":{"convention":{"const":"modern"}},"required":["convention"]}]},{"type":"null"}]}},"required":["ascendant","traditional","modern"]},{"type":"null"}]}},"required":["chart_ruler"],"additionalProperties":true}}}},"400":{"description":"Invalid input; message explains how to fix it"}}}},"/api/v1/sky":{"get":{"operationId":"getPlanetPositions","summary":"Planet positions and retrogrades at a moment","description":"Where each planet is and which are retrograde. Default: now. Use for 'is Mercury retrograde' questions.","parameters":[{"name":"date","in":"query","required":false,"description":"ISO 8601 date/datetime in UTC; omit for now","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language for sign/planet names and the reading (en, es, it, fr). Default en.","schema":{"type":"string","enum":["en","es","it","fr"]}}],"responses":{"200":{"description":"Positions as JSON"}}}}},"components":{"schemas":{"ChartRulerPlacement":{"type":"object","properties":{"convention":{"type":"string","enum":["traditional","modern"]},"planet":{"type":"string"},"name":{"type":"string","description":"Localized planet name."},"sign":{"type":"string"},"sign_localized":{"type":"string"},"degree_in_sign":{"type":"number"},"formatted":{"type":"string"},"house":{"type":"integer","minimum":1,"maximum":12}},"required":["convention","planet","name","sign","sign_localized","degree_in_sign","formatted","house"]}}}}