openapi: 3.1.0
info:
    title: Age Calculator API
    description: Calculate exact age, zodiac signs, generation, planetary ages and more from a birth date.
    version: 1.0.0
servers:
    - url: https://myagecalculator.net
paths:
    /api/calculate:
        get:
            operationId: calculateAge
            summary: Calculate age and related data from a birth date
            parameters:
                - name: birthdate
                  in: query
                  required: true
                  schema:
                      type: string
                      format: date
                  description: "Date of birth in YYYY-MM-DD format"
                  example: "1990-06-15"
                - name: parentdate
                  in: query
                  required: false
                  schema:
                      type: string
                      format: date
                  description: "Parent's date of birth in YYYY-MM-DD format (optional)"
                  example: "1960-03-10"
                - name: lang
                  in: query
                  required: false
                  schema:
                      type: string
                      enum: [en, cs, de, fr, es, it, pt, nl, pl, sk, ro, hu, bg, hr, sl, da, fi, sv, no, el, et, lt, lv, ga, mt, zh, ja, ko, ar, hi, tr, ru, uk, id, vi, th, bn, ur, fa, he, sw, ms, tl, my, am, pa, ta, te, mr, gu, kn, or, ml, jv, ha, yo, ig, zu]
                  description: "Language code for translated results. Falls back to Accept-Language header, then English."
                  example: "cs"
            responses:
                "200":
                    description: Age calculation results
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    birthDate:
                                        type: string
                                        format: date
                                    calculatedAt:
                                        type: string
                                        format: date
                                    age:
                                        type: object
                                        properties:
                                            years:
                                                type: integer
                                            months:
                                                type: integer
                                            days:
                                                type: integer
                                    ageInUnits:
                                        type: object
                                        properties:
                                            totalDays:
                                                type: integer
                                            totalHours:
                                                type: integer
                                            totalMinutes:
                                                type: integer
                                            totalSeconds:
                                                type: integer
                                    dayOfWeek:
                                        type: string
                                    zodiac:
                                        type: object
                                        properties:
                                            sign:
                                                type: string
                                            emoji:
                                                type: string
                                    chineseZodiac:
                                        type: object
                                        properties:
                                            animal:
                                                type: string
                                            emoji:
                                                type: string
                                    moonPhase:
                                        type: object
                                        properties:
                                            phase:
                                                type: string
                                            emoji:
                                                type: string
                                    generation:
                                        type: object
                                        nullable: true
                                        properties:
                                            name:
                                                type: string
                                            description:
                                                type: string
                                    milestones:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                label:
                                                    type: string
                                                date:
                                                    type: string
                                                    format: date
                                                passed:
                                                    type: boolean
                                    planetaryAges:
                                        type: object
                                        additionalProperties:
                                            type: object
                                            properties:
                                                age:
                                                    type: number
                                                fullOrbits:
                                                    type: integer
                                                    nullable: true
                                    futureAgeTable:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                year:
                                                    type: integer
                                                age:
                                                    type: integer
                                    targetAges:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                age:
                                                    type: integer
                                                date:
                                                    type: string
                                                    format: date
                                                daysFromNow:
                                                    type: integer
                                    parentComparison:
                                        type: object
                                        nullable: true
                                        properties:
                                            parentBirthDate:
                                                type: string
                                                format: date
                                            sameAgeDate:
                                                type: string
                                                format: date
                "400":
                    description: Invalid input
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
