{"openapi":"3.1.0","info":{"title":"Chinese Gender Calendar game API","version":"1.0.0","description":"Calculate entertainment-game results using the same Chinese and Maya calculators as the website. These rules do not determine a baby’s sex or provide a validated probability. Dates are processed in request memory, not recorded by the application, not echoed in responses, and not sent to analytics or another calculation service. Use a POST JSON body, never URL parameters. API responses use no-store headers. The website forms continue calculating locally in the browser."},"servers":[{"url":"https://www.chinese-gender-calendar.app"}],"security":[],"paths":{"/api/v1/predict":{"post":{"operationId":"predictCalendarGames","parameters":[{"in":"header","name":"User-Agent","required":false,"description":"Identify scripted clients, for example CalendarAssistant/1.0. Cloudflare can reject generic script user agents before the request reaches this API (HTTP 403, error code 1010). Browsers supply their own User-Agent.","schema":{"type":"string","minLength":1},"example":"CalendarAssistant/1.0"}],"summary":"Get Chinese and Maya calendar game results","description":"Returns both games by default, or the selected game. HTTP 200 can contain status partial when only one game accepts the age; inspect each result's status. HTTP 422 with results means all requested games are unavailable. Other validation errors contain an error object instead of results. There are no query parameters or authentication requirements. Send an uncompressed JSON body of at most 1024 bytes. No cookies are required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionRequest"},"example":{"birthDate":"1998-06-15","conceptionDate":"2026-02-17","calendar":"both","locale":"en"}}}},"responses":{"200":{"description":"At least one requested game result is available. Inspect the top-level status (ok or partial) and each game status.","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"private, no-store, max-age=0"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"},"example":{"apiVersion":"1","purpose":"entertainment","locale":"en","status":"ok","results":{"chinese":{"status":"ok","gender":"girl","label":"Girl","explanation":"The cell at nominal age 29 and lunar month 1 gives: Girl.","chineseAge":29,"lunarMonth":1,"isLeapMonth":false,"sourceUrl":"https://www.chinese-gender-calendar.app/chinese-gender-calendars"},"mayan":{"status":"ok","gender":"girl","label":"Girl","explanation":"27 + 17 = 44: the sum is even, so the game gives girl.","motherAgeAtConception":27,"haabMonthNumber":17,"haabMonthName":"Kayab","sum":44,"remainder":0,"sourceUrl":"https://www.chinese-gender-calendar.app/mayan-gender-calendars"}}}}}},"400":{"description":"Malformed UTF-8 JSON or URL query parameters.","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"private, no-store, max-age=0"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"},"examples":{"query_parameters_not_allowed":{"value":{"apiVersion":"1","error":{"code":"query_parameters_not_allowed","message":"Send the inputs in the JSON request body, without URL query parameters."}}},"invalid_json":{"value":{"apiVersion":"1","error":{"code":"invalid_json","message":"Send a valid UTF-8 JSON object."}}}}}}},"403":{"description":"Cloudflare can reject generic script user agents before the request reaches the application. Use an identifying User-Agent, for example CalendarAssistant/1.0. This infrastructure response is plain text, not an API validation error.","content":{"text/plain":{"schema":{"type":"string"},"example":"error code: 1010\n"}}},"405":{"description":"This endpoint accepts POST and OPTIONS only.","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"private, no-store, max-age=0"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"},"examples":{"method_not_allowed":{"value":{"apiVersion":"1","error":{"code":"method_not_allowed","message":"Use POST with a JSON request body."}}}}}}},"413":{"description":"Request body exceeds 1024 bytes.","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"private, no-store, max-age=0"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"},"examples":{"request_too_large":{"value":{"apiVersion":"1","error":{"code":"request_too_large","message":"The JSON request body must not exceed 1024 bytes."}}}}}}},"415":{"description":"Use an uncompressed application/json body.","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"private, no-store, max-age=0"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"},"examples":{"unsupported_media_type":{"value":{"apiVersion":"1","error":{"code":"unsupported_media_type","message":"Use Content-Type: application/json and an uncompressed UTF-8 body."}}}}}}},"422":{"description":"Invalid fields or dates (error object), or every requested game is outside its supported age/conversion range (results object).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ApiErrorResponse"},{"$ref":"#/components/schemas/PredictionResponse"}]},"examples":{"invalid_request":{"value":{"apiVersion":"1","error":{"code":"invalid_request","message":"Use birthDate and conceptionDate as YYYY-MM-DD strings, an optional calendar (chinese, mayan or both) and an optional locale (ar, de, en, es, fr or pt). Additional fields are not accepted."}}},"invalid_dates":{"value":{"apiVersion":"1","error":{"code":"invalid_dates","message":"Use real calendar dates from 1900 to 2050, with conception after birth."}}}}}}},"500":{"description":"Generic failure. Request content and exception details are not included.","headers":{"Cache-Control":{"schema":{"type":"string"},"example":"private, no-store, max-age=0"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"},"examples":{"internal_error":{"value":{"apiVersion":"1","error":{"code":"internal_error","message":"The calculation could not be completed."}}}}}}}}}}},"components":{"schemas":{"PredictionRequest":{"type":"object","additionalProperties":false,"required":["birthDate","conceptionDate"],"properties":{"birthDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","minLength":10,"maxLength":10,"description":"Mother’s birth date as a Gregorian civil date (1900–2050). No time or timezone. Must be before conceptionDate."},"conceptionDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","minLength":10,"maxLength":10,"description":"Estimated conception date as a Gregorian civil date (1900–2050), not a due date. No time or timezone."},"calendar":{"type":"string","enum":["chinese","mayan","both"],"default":"both"},"locale":{"type":"string","enum":["ar","de","en","es","fr","pt"],"default":"en","description":"Language of labels, explanations and canonical links. pt uses Portuguese from Portugal."}}},"ApiError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string","description":"Safe explanation without any submitted values."}}},"ApiErrorResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"$ref":"#/components/schemas/ApiError"}}},"GameUnavailable":{"type":"object","additionalProperties":false,"required":["status","error","sourceUrl"],"properties":{"status":{"type":"string","const":"unavailable"},"error":{"$ref":"#/components/schemas/ApiError"},"sourceUrl":{"type":"string","format":"uri","description":"Canonical HTML entry page explaining this game in the selected language."}}},"ChineseResult":{"type":"object","additionalProperties":false,"required":["status","gender","label","explanation","sourceUrl","chineseAge","lunarMonth","isLeapMonth"],"properties":{"status":{"type":"string","const":"ok"},"gender":{"type":"string","enum":["boy","girl"]},"label":{"type":"string","description":"Result label in the selected language."},"explanation":{"type":"string","description":"Explanation from the existing calculator copy, in the selected language."},"sourceUrl":{"type":"string","format":"uri","description":"Canonical HTML entry page explaining this game in the selected language."},"chineseAge":{"type":"integer","minimum":18,"maximum":43,"description":"Chinese nominal age: conception lunar year minus birth lunar year, plus one."},"lunarMonth":{"type":"integer","minimum":1,"maximum":12},"isLeapMonth":{"type":"boolean","description":"A repeated lunar month uses the same game column as the ordinary month with this number."}}},"MayanResult":{"type":"object","additionalProperties":false,"required":["status","gender","label","explanation","sourceUrl","motherAgeAtConception","haabMonthNumber","haabMonthName","sum","remainder"],"properties":{"status":{"type":"string","const":"ok"},"gender":{"type":"string","enum":["boy","girl"]},"label":{"type":"string","description":"Result label in the selected language."},"explanation":{"type":"string","description":"Explanation from the existing calculator copy, in the selected language."},"sourceUrl":{"type":"string","format":"uri","description":"Canonical HTML entry page explaining this game in the selected language."},"motherAgeAtConception":{"type":"integer","minimum":16,"maximum":50,"description":"Completed Gregorian age on conceptionDate."},"haabMonthNumber":{"type":"integer","minimum":1,"maximum":19,"description":"Game period number; Wayeb/Uayeb is 19."},"haabMonthName":{"type":"string"},"sum":{"type":"integer","description":"Completed age plus the Haab period number."},"remainder":{"type":"integer","enum":[0,1],"description":"The existing game’s sum modulo two: 0 gives girl, 1 gives boy."}}},"PredictionResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","purpose","locale","status","results"],"properties":{"apiVersion":{"type":"string","const":"1"},"purpose":{"type":"string","const":"entertainment"},"locale":{"type":"string","enum":["ar","de","en","es","fr","pt"]},"status":{"type":"string","enum":["ok","partial","unavailable"]},"results":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"chinese":{"oneOf":[{"$ref":"#/components/schemas/ChineseResult"},{"$ref":"#/components/schemas/GameUnavailable"}]},"mayan":{"oneOf":[{"$ref":"#/components/schemas/MayanResult"},{"$ref":"#/components/schemas/GameUnavailable"}]}}}}}}}}