openapi.yaml

openapi: 3.1.0
info:
  title: Planets360 - Vedic Astrology API
  description: |
    Trimmed Planets360 spec - only the 7 endpoints needed.
    Every action accepts GET (query string) or POST (JSON body).
    Success returns the raw report output; failures return {status, error}.
  version: 1.0.0
  contact:
    name: Planets360
    url: https://ephemeris.gopim.dev/
  license:
    name: Proprietary - Planets360
servers:
  - url: https://ephemeris.gopim.dev
    description: Production (Planets360 via nginx + TLS)
  - url: http://localhost:8080
    description: Local development (EphemerisUiServer)
security:
  - ApiKeyAuth: []
  - BearerAuth: []
  - {}
tags:
  - name: Kundli
    description: Birth chart and planetary positions.
  - name: Transits
    description: Planetary transits over a year range.
  - name: Dasa
    description: Vimshottari dasa / bhukti timeline.
  - name: Chandrashtama
    description: Debilitated-moon days of a year.
  - name: Panchapakshi
    description: Panchapakshi bird and daily table.
  - name: Compatibility
    description: Love calculator compatibility.
  - name: Predictions
    description: Moon-sign predictions over a date range.
paths:
  /api/v1/panchang-fast:
    get:
      tags: [Kundli]
      summary: Fast Panchang - also used as Kundli
      description: |
        Same fields and values as Panchang (Daily), on the optimised engine.
        Pass birth date/time/location for a kundli (birth chart + planetary
        positions), or any date for a daily fast panchang.
        Params: latitude, longitude, timeZone, year, month, day, hour, minute.
      operationId: getFastPanchang
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - $ref: '#/components/parameters/YearQuery'
        - $ref: '#/components/parameters/MonthQuery'
        - $ref: '#/components/parameters/DayQuery'
        - $ref: '#/components/parameters/HourQuery'
        - $ref: '#/components/parameters/MinuteQuery'
      responses:
        '200':
          description: Panchang / kundli report (JSON)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PanchangResponse'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '500': {$ref: '#/components/responses/ServerError'}
    post:
      tags: [Kundli]
      summary: Fast Panchang via JSON body
      operationId: postFastPanchang
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GeoDateTimeRequest'}
            example:
              latitude: '13.0827'
              longitude: '80.2707'
              timeZone: Asia/Kolkata
              year: 1990
              month: 1
              day: 1
              hour: 10
              minute: 30
      responses:
        '200':
          description: Panchang / kundli report (JSON)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PanchangResponse'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '500': {$ref: '#/components/responses/ServerError'}
  /api/v1/planet-transit-range:
    get:
      tags: [Transits]
      summary: Planet transits over a year range
      description: |
        Sign-by-sign transit of one planet across a year range, with retrograde,
        progressive and combustion markers. Params: latitude, longitude,
        timeZone, startYear, endYear, planetName.
      operationId: getTransitRange
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - name: startYear
          in: query
          required: true
          schema: {type: integer, example: 2026}
        - name: endYear
          in: query
          required: true
          schema: {type: integer, example: 2030}
        - name: planetName
          in: query
          required: true
          schema:
            type: string
            enum: [Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu, Lagna]
            example: Mercury
      responses:
        '200':
          description: Transit segments (JSON array)
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/TransitSegment'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
    post:
      tags: [Transits]
      summary: Planet transits over a year range via JSON body
      operationId: postTransitRange
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/TransitRangeRequest'}
            example:
              latitude: '13.0827'
              longitude: '80.2707'
              timeZone: Asia/Kolkata
              startYear: 2026
              endYear: 2030
              planetName: Mercury
      responses:
        '200':
          description: Transit segments (JSON array)
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/TransitSegment'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /api/v1/dasa-bhukti:
    get:
      tags: [Dasa]
      summary: Vimshottari dasa / bhukti / antara timeline
      operationId: getDasaBhukti
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - $ref: '#/components/parameters/YearQuery'
        - $ref: '#/components/parameters/MonthQuery'
        - $ref: '#/components/parameters/DayQuery'
        - $ref: '#/components/parameters/HourQuery'
        - $ref: '#/components/parameters/MinuteQuery'
      responses:
        '200':
          description: Dasa bhukti antara timeline (JSON)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DasaBhuktiResponse'}
    post:
      tags: [Dasa]
      summary: Dasa bhukti via JSON body
      operationId: postDasaBhukti
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GeoDateTimeRequest'}
      responses:
        '200':
          description: Dasa bhukti antara timeline (JSON)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DasaBhuktiResponse'}
  /api/v1/charashamata-days:
    get:
      tags: [Chandrashtama]
      summary: Chandrashtama days of a year
      description: |
        The 60 Chandra Shatamata (debilitated moon) days of a year, each with
        sign, start/end and nakshatra-pada breakdown.
        Params: latitude, longitude, timeZone, year.
      operationId: getChandrashtamaDays
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - $ref: '#/components/parameters/YearQuery'
      responses:
        '200':
          description: Chandrashtama days (JSON array)
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/ChandrashtamaDay'}
    post:
      tags: [Chandrashtama]
      summary: Chandrashtama days via JSON body
      operationId: postChandrashtamaDays
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GeoYearRequest'}
      responses:
        '200':
          description: Chandrashtama days (JSON array)
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/ChandrashtamaDay'}
  /api/v1/panchapakshi:
    get:
      tags: [Panchapakshi]
      summary: Daily Panchapakshi table for a bird
      description: |
        Daily day/night action sequence for a bird and birth moment.
        Adds param bird: Peacock, Crow, Owl, Rooster, Vulture.
      operationId: getPanchapakshi
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - $ref: '#/components/parameters/YearQuery'
        - $ref: '#/components/parameters/MonthQuery'
        - $ref: '#/components/parameters/DayQuery'
        - $ref: '#/components/parameters/HourQuery'
        - $ref: '#/components/parameters/MinuteQuery'
        - name: bird
          in: query
          required: true
          schema:
            type: string
            enum: [Peacock, Crow, Owl, Rooster, Vulture]
            example: Peacock
      responses:
        '200':
          description: Panchapakshi tables (JSON)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PanchapakshiResponse'}
    post:
      tags: [Panchapakshi]
      summary: Daily Panchapakshi table via JSON body
      operationId: postPanchapakshi
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/PanchapakshiRequest'}
      responses:
        '200':
          description: Panchapakshi tables (JSON)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PanchapakshiResponse'}
  /api/v1/find-bird-by-birth-info:
    get:
      tags: [Panchapakshi]
      summary: Resolve Panchapakshi bird from birth moment
      operationId: getBirdByBirthInfo
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - $ref: '#/components/parameters/YearQuery'
        - $ref: '#/components/parameters/MonthQuery'
        - $ref: '#/components/parameters/DayQuery'
        - $ref: '#/components/parameters/HourQuery'
        - $ref: '#/components/parameters/MinuteQuery'
      responses:
        '200':
          description: Bird details (JSON)
          content:
            application/json: {schema: {type: object}}
    post:
      tags: [Panchapakshi]
      summary: Resolve bird from birth moment via body
      operationId: postBirdByBirthInfo
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GeoDateTimeRequest'}
      responses:
        '200':
          description: Bird details (JSON)
          content:
            application/json: {schema: {type: object}}
  /api/v1/find-bird-by-nakshatra:
    get:
      tags: [Panchapakshi]
      summary: Resolve Panchapakshi bird from birth star
      operationId: getBirdByNakshatra
      parameters:
        - name: birthStar
          in: query
          required: true
          schema: {type: string, example: Vishakha}
      responses:
        '200':
          description: Bird details (JSON)
          content:
            application/json: {schema: {type: object}}
    post:
      tags: [Panchapakshi]
      summary: Resolve bird from birth star via body
      operationId: postBirdByNakshatra
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [birthStar]
              properties:
                birthStar: {type: string, example: Vishakha}
      responses:
        '200':
          description: Bird details (JSON)
          content:
            application/json: {schema: {type: object}}
  /api/v1/find-bird-by-name:
    get:
      tags: [Panchapakshi]
      summary: Resolve Panchapakshi bird from name
      operationId: getBirdByName
      parameters:
        - name: name
          in: query
          required: true
          schema: {type: string, example: Gopi}
      responses:
        '200':
          description: Bird details (JSON)
          content:
            application/json: {schema: {type: object}}
    post:
      tags: [Panchapakshi]
      summary: Resolve bird from name via body
      operationId: postBirdByName
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: {type: string, example: Gopi}
      responses:
        '200':
          description: Bird details (JSON)
          content:
            application/json: {schema: {type: object}}
  /api/v1/lc-birth-date-based:
    get:
      tags: [Compatibility]
      summary: Love compatibility from birth dates
      operationId: getLoveByBirthDate
      parameters:
        - name: boyBirthDate
          in: query
          required: true
          schema: {type: string, format: date, example: '2019-03-01'}
        - name: girlBirthDate
          in: query
          required: true
          schema: {type: string, format: date, example: '2019-03-07'}
        - $ref: '#/components/parameters/TimeZoneQuery'
      responses:
        '200':
          description: Compatibility score 0-100 (integer)
          content:
            application/json: {schema: {type: integer, example: 85}}
            text/plain: {schema: {type: string}}
    post:
      tags: [Compatibility]
      summary: Love compatibility from birth dates via body
      operationId: postLoveByBirthDate
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/LoveBirthDateRequest'}
      responses:
        '200':
          description: Compatibility score 0-100 (integer)
          content:
            application/json: {schema: {type: integer, example: 85}}
            text/plain: {schema: {type: string}}
  /api/v1/lc-moon-sign-based:
    get:
      tags: [Compatibility]
      summary: Love compatibility from moon signs
      operationId: getLoveByMoonSign
      parameters:
        - name: boyMoonSign
          in: query
          required: true
          schema: {type: string, example: Libra}
        - name: girlMoonSign
          in: query
          required: true
          schema: {type: string, example: Sagittarius}
      responses:
        '200':
          description: Compatibility score 0-100 (integer)
          content:
            application/json: {schema: {type: integer, example: 78}}
            text/plain: {schema: {type: string}}
    post:
      tags: [Compatibility]
      summary: Love compatibility from moon signs via body
      operationId: postLoveByMoonSign
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/LoveMoonSignRequest'}
      responses:
        '200':
          description: Compatibility score 0-100 (integer)
          content:
            application/json: {schema: {type: integer, example: 78}}
            text/plain: {schema: {type: string}}
  /api/v1/lc-name-based:
    get:
      tags: [Compatibility]
      summary: Love compatibility from names
      operationId: getLoveByName
      parameters:
        - name: boyName
          in: query
          required: true
          schema: {type: string, example: Deepak raj}
        - name: girlName
          in: query
          required: true
          schema: {type: string, example: Dharini}
      responses:
        '200':
          description: Compatibility score 0-100 (integer)
          content:
            application/json: {schema: {type: integer, example: 92}}
            text/plain: {schema: {type: string}}
    post:
      tags: [Compatibility]
      summary: Love compatibility from names via body
      operationId: postLoveByName
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/LoveNameRequest'}
      responses:
        '200':
          description: Compatibility score 0-100 (integer)
          content:
            application/json: {schema: {type: integer, example: 92}}
            text/plain: {schema: {type: string}}
  /api/v1/moon-sign-prediction:
    get:
      tags: [Predictions]
      summary: Moon-sign prediction over a date range
      description: |
        Day-wise Moon transit with Chandra/Tara Bala, conjunctions,
        retrogression, combustion, aspects and daily yoga.
        Params: latitude, longitude, timeZone, startDate, endDate (yyyy-MM-dd),
        moonSign (Aries..Pisces), natalNakshatra (27 stars).
      operationId: getMoonSignPrediction
      parameters:
        - $ref: '#/components/parameters/LatitudeQuery'
        - $ref: '#/components/parameters/LongitudeQuery'
        - $ref: '#/components/parameters/TimeZoneQuery'
        - name: startDate
          in: query
          required: true
          schema: {type: string, format: date, example: '2026-09-30'}
        - name: endDate
          in: query
          required: true
          schema: {type: string, format: date, example: '2026-10-05'}
        - name: moonSign
          in: query
          required: true
          schema: {type: string, example: Taurus}
        - name: natalNakshatra
          in: query
          required: true
          schema: {type: string, example: Rohini}
      responses:
        '200':
          description: Prediction segments (JSON)
          content:
            application/json: {schema: {type: object}}
    post:
      tags: [Predictions]
      summary: Moon-sign prediction via JSON body
      operationId: postMoonSignPrediction
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/MoonSignPredictionRequest'}
      responses:
        '200':
          description: Prediction segments (JSON)
          content:
            application/json: {schema: {type: object}}
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Shared secret (EPHEMERIS_API_KEY). Unset locally means open access.
    BearerAuth:
      type: http
      scheme: bearer
      description: Same secret as Authorization Bearer.
  parameters:
    LatitudeQuery:
      name: latitude
      in: query
      required: true
      description: Decimal degrees -90 to 90.
      schema: {type: string, example: '13.0827'}
    LongitudeQuery:
      name: longitude
      in: query
      required: true
      description: Decimal degrees -180 to 180.
      schema: {type: string, example: '80.2707'}
    TimeZoneQuery:
      name: timeZone
      in: query
      required: true
      description: IANA id e.g. Asia/Kolkata.
      schema: {type: string, example: Asia/Kolkata}
    YearQuery:
      name: year
      in: query
      required: true
      schema: {type: string, example: '2026'}
    MonthQuery:
      name: month
      in: query
      required: true
      schema: {type: string, example: '9'}
    DayQuery:
      name: day
      in: query
      required: true
      schema: {type: string, example: '29'}
    HourQuery:
      name: hour
      in: query
      required: true
      schema: {type: string, example: '10'}
    MinuteQuery:
      name: minute
      in: query
      required: true
      schema: {type: string, example: '30'}
  schemas:
    GeoDateTimeRequest:
      type: object
      required: [latitude, longitude, timeZone, year, month, day, hour, minute]
      properties:
        latitude: {type: string, example: '13.0827'}
        longitude: {type: string, example: '80.2707'}
        timeZone: {type: string, example: Asia/Kolkata}
        year: {type: integer, example: 1990}
        month: {type: integer, example: 1}
        day: {type: integer, example: 1}
        hour: {type: integer, example: 10}
        minute: {type: integer, example: 30}
    GeoYearRequest:
      type: object
      required: [latitude, longitude, timeZone, year]
      properties:
        latitude: {type: string, example: '13.0827'}
        longitude: {type: string, example: '80.2707'}
        timeZone: {type: string, example: Asia/Kolkata}
        year: {type: integer, example: 2026}
    TransitRangeRequest:
      type: object
      required: [latitude, longitude, timeZone, startYear, endYear, planetName]
      properties:
        latitude: {type: string, example: '13.0827'}
        longitude: {type: string, example: '80.2707'}
        timeZone: {type: string, example: Asia/Kolkata}
        startYear: {type: integer, example: 2026}
        endYear: {type: integer, example: 2030}
        planetName: {type: string, example: Mercury}
    PanchapakshiRequest:
      allOf:
        - $ref: '#/components/schemas/GeoDateTimeRequest'
        - type: object
          required: [bird]
          properties:
            bird: {type: string, example: Peacock}
    LoveBirthDateRequest:
      type: object
      required: [boyBirthDate, girlBirthDate, timeZone]
      properties:
        boyBirthDate: {type: string, example: '2019-03-01'}
        girlBirthDate: {type: string, example: '2019-03-07'}
        timeZone: {type: string, example: Asia/Kolkata}
    LoveMoonSignRequest:
      type: object
      required: [boyMoonSign, girlMoonSign]
      properties:
        boyMoonSign: {type: string, example: Libra}
        girlMoonSign: {type: string, example: Sagittarius}
    LoveNameRequest:
      type: object
      required: [boyName, girlName]
      properties:
        boyName: {type: string, example: Deepak raj}
        girlName: {type: string, example: Dharini}
    MoonSignPredictionRequest:
      type: object
      required: [latitude, longitude, timeZone, startDate, endDate, moonSign, natalNakshatra]
      properties:
        latitude: {type: string, example: '13.0827'}
        longitude: {type: string, example: '80.2707'}
        timeZone: {type: string, example: Asia/Kolkata}
        startDate: {type: string, example: '2026-09-30'}
        endDate: {type: string, example: '2026-10-05'}
        moonSign: {type: string, example: Taurus}
        natalNakshatra: {type: string, example: Rohini}
    PanchangResponse:
      type: object
      description: Raw fast-panchang / kundli output.
      properties:
        SunriseTime: {type: string}
        SunsetTime: {type: string}
        nakshatra:
          type: object
          properties:
            NakshatraName: {type: string, example: Rohini}
        tithi:
          type: object
          properties:
            TithiName: {type: string}
            MoonPhase: {type: string}
        yoga:
          type: object
          properties:
            YogaName: {type: string}
    TransitSegment:
      type: object
      properties:
        planet: {type: string, example: Mercury}
        transitSign: {type: string}
        transitStartDate: {type: string}
        transitEndDate: {type: string}
        durationDays: {type: integer}
        retrograde: {type: boolean}
        combust: {type: boolean}
    DasaBhuktiResponse:
      type: object
      description: Dasa/bhukti/antara timeline.
      properties:
        BirthInformationDetailsWithDasaBhukti: {type: object}
    ChandrashtamaDay:
      type: object
      properties:
        sign: {type: string}
        startDate: {type: string}
        endDate: {type: string}
    PanchapakshiResponse:
      type: object
      properties:
        Bird: {type: string, example: Peacock}
        DayOfWeek: {type: string}
        MoonPhase: {type: string}
    Error:
      type: object
      required: [status, error]
      properties:
        status: {type: integer, example: 400}
        error: {type: string}
  responses:
    BadRequest:
      description: Body or query cannot be read
      content:
        application/json: {schema: {$ref: '#/components/schemas/Error'}}
    Unauthorized:
      description: Missing key (only when server key is set)
      content:
        application/json: {schema: {$ref: '#/components/schemas/Error'}}
    ServerError:
      description: Fault inside a report
      content:
        application/json: {schema: {$ref: '#/components/schemas/Error'}}