{"openapi":"3.1.0","info":{"title":"Unified Reading API","version":"1.0.0","summary":"Date-only numerology, Western Sun sign and Chinese zodiac calculations.","description":"A public, read-only API from Unified Reading. It needs no authentication and stores nothing. It takes only a birth date: never send names, birth times or places. The full personal reading is only available through the website form. Versioning: additive changes only within v1; a breaking change ships as /api/v2, and v1 then keeps working for at least 90 days with Deprecation (RFC 9745) and Sunset (RFC 8594) headers. No version is deprecated today.","contact":{"name":"Unified Reading","url":"https://unifiedreading.com/contact"}},"externalDocs":{"description":"API guide","url":"https://unifiedreading.com/docs"},"servers":[{"url":"https://unifiedreading.com"}],"security":[],"tags":[{"name":"profile","description":"Calculated values for a birth date."},{"name":"chinese-zodiac","description":"The Lunar New Year table behind the Chinese zodiac."}],"paths":{"/api/v1/profile":{"get":{"operationId":"getBirthDateProfile","tags":["profile"],"summary":"Birth date profile","description":"Returns the Life Path number (master numbers 11, 22 and 33 kept), the Western Sun sign with decan, element, modality and ruler, and the Chinese zodiac animal with element and yin-yang, decided by the Lunar New Year date. Each part links to its library guide. Rate limit: 10 requests per minute per IP.","parameters":[{"name":"date","in":"query","required":true,"description":"Birth date as YYYY-MM-DD, from 1900 up to today.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["1990-07-14"]}}],"responses":{"200":{"description":"The calculated profile.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Missing or invalid date.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method other than GET.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/profiles/batch":{"post":{"operationId":"batchGetBirthDateProfiles","tags":["profile"],"summary":"Batch birth date profiles","description":"The same profile as GET /api/v1/profile for up to 20 dates, in request order. An invalid date fails only its own item. The calculation has no side effects, so retries are safe; an Idempotency-Key is validated and echoed back so a client can match a retry to its first attempt.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key (1-255 visible ASCII characters, a UUID is typical), echoed in the response.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dates"],"additionalProperties":false,"properties":{"dates":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"examples":[["1990-07-14","1990-01-20"]]}}}}}},"responses":{"200":{"description":"One result per date.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}},"Idempotency-Key":{"description":"The request's key, when one was sent.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResult"}}}}}}},"400":{"description":"Body is not JSON, dates is not 1-20 strings, or the Idempotency-Key is malformed.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method other than POST.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chinese-zodiac/years":{"get":{"operationId":"listChineseZodiacYears","tags":["chinese-zodiac"],"summary":"Chinese zodiac years","description":"Every zodiac year from 1924 to 2044 with its animal, stem element, yin-yang and the Lunar New Year dates it starts and ends on. Cursor-paginated: follow next_cursor (or the Link rel=next header) until has_more is false.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1-60.","schema":{"type":"integer","minimum":1,"maximum":60,"default":12}},{"name":"cursor","in":"query","required":false,"description":"The next_cursor value from the previous page. Leave it out to start at 1924.","schema":{"type":"string","examples":["1936"]}}],"responses":{"200":{"description":"One page of years.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}},"Link":{"description":"RFC 8288 link to the next page (rel=\"next\"), when there is one.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/YearPage"}}}},"400":{"description":"limit out of range or cursor not a year in the table.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","headers":{"RateLimit-Limit":{"description":"Requests allowed per minute per IP.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the window frees a request.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint","status","docs"],"properties":{"code":{"type":"string","enum":["invalid_date","invalid_body","invalid_cursor","invalid_idempotency_key","missing_parameter","not_found","method_not_allowed","rate_limited"],"description":"Stable machine-readable error code."},"message":{"type":"string","description":"What went wrong."},"hint":{"type":"string","description":"How to fix the request."},"status":{"type":"integer","description":"HTTP status code, repeated in the body."},"docs":{"type":"string","format":"uri"}}}}},"BatchResult":{"type":"object","required":["date","ok"],"properties":{"date":{"type":["string","null"],"description":"The date as sent; null if it was not a string."},"ok":{"type":"boolean"},"profile":{"$ref":"#/components/schemas/Profile","description":"Present when ok is true."},"error":{"type":"object","description":"Present when ok is false.","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_date"]},"message":{"type":"string"}}}}},"YearPage":{"type":"object","required":["data","has_more","next_cursor","next","total"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ZodiacYear"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next":{"type":["string","null"],"format":"uri"},"total":{"type":"integer","description":"Years in the whole table."}}},"ZodiacYear":{"type":"object","required":["year","animal","element","yinYang","starts","ends","guide"],"properties":{"year":{"type":"integer","minimum":1924,"maximum":2044},"animal":{"type":"string","enum":["Rat","Ox","Tiger","Rabbit","Dragon","Snake","Horse","Goat","Monkey","Rooster","Dog","Pig"]},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"yinYang":{"type":"string","enum":["Yin","Yang"]},"starts":{"type":"string","format":"date","description":"Lunar New Year: the first day of the zodiac year."},"ends":{"type":["string","null"],"format":"date","description":"The day before the next Lunar New Year; null for 2044, the end of the table."},"guide":{"type":"string","format":"uri"}}},"Profile":{"type":"object","required":["date","lifePath","sunSign","chineseZodiac","notes","fullReading"],"properties":{"date":{"type":"string","format":"date"},"lifePath":{"type":"object","required":["number","title","brief","keywords","guide"],"properties":{"number":{"type":"integer","enum":[1,2,3,4,5,6,7,8,9,11,22,33]},"title":{"type":"string"},"brief":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"guide":{"type":"string","format":"uri"}}},"sunSign":{"type":"object","required":["sign","glyph","decan","element","modality","rulingPlanet","guide"],"properties":{"sign":{"type":"string","examples":["Cancer"]},"glyph":{"type":"string"},"decan":{"type":"integer","minimum":1,"maximum":3},"element":{"type":"string","enum":["Fire","Earth","Air","Water"]},"modality":{"type":"string","enum":["Cardinal","Fixed","Mutable"]},"rulingPlanet":{"type":"string"},"guide":{"type":"string","format":"uri"}}},"chineseZodiac":{"type":"object","required":["animal","element","yinYang","bestWith","guide"],"properties":{"animal":{"type":"string","examples":["Horse"]},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"yinYang":{"type":"string","enum":["Yin","Yang"]},"bestWith":{"type":"array","items":{"type":"string"}},"guide":{"type":"string","format":"uri"}}},"notes":{"type":"array","items":{"type":"string"}},"fullReading":{"type":"string","format":"uri","description":"Where the person can start their own combined reading."}}}}}}