{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-tidal-forcing-response-schema.json",
  "title": "TidalForcingResponse",
  "description": "Full tidal forcing analysis for a location and time.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openephemeris-com-tidal-api-openapi.yml#/components/schemas/TidalForcingResponse",
  "properties": {
    "date": {
      "description": "Date in YYYY-MM-DD format (if requested by date)",
      "title": "Date",
      "type": "string"
    },
    "equilibrium": {
      "allOf": [
        {
          "$ref": "#/$defs/EquilibriumTide"
        }
      ],
      "description": "Theoretical equilibrium tide heights"
    },
    "forcing_indices": {
      "allOf": [
        {
          "$ref": "#/$defs/ForcingIndices"
        }
      ],
      "description": "Computed forcing indicators"
    },
    "julian_day": {
      "description": "Julian Day of the calculation",
      "format": "double",
      "title": "Julian Day",
      "type": "number"
    },
    "lunar": {
      "allOf": [
        {
          "$ref": "#/$defs/TidalLunarData"
        }
      ],
      "description": "Lunar parameters"
    },
    "meta": {
      "allOf": [
        {
          "$ref": "#/$defs/TidalMeta"
        }
      ],
      "description": "Metadata and disclaimers"
    },
    "observer": {
      "allOf": [
        {
          "$ref": "#/$defs/Observer"
        }
      ],
      "description": "Observer location"
    },
    "solar": {
      "allOf": [
        {
          "$ref": "#/$defs/TidalSolarData"
        }
      ],
      "description": "Solar parameters"
    },
    "timezone": {
      "description": "IANA zone the perigee, apogee and syzygy times are written in: the zone at the coordinates.",
      "type": "string"
    }
  },
  "required": [
    "meta",
    "date",
    "julian_day",
    "observer",
    "lunar",
    "solar",
    "forcing_indices",
    "equilibrium"
  ],
  "type": "object",
  "$defs": {
    "EquilibriumTide": {
      "properties": {
        "combined_m": {
          "description": "Combined equilibrium tide (meters)",
          "title": "Combined M",
          "type": "number"
        },
        "lunar_component_m": {
          "description": "Lunar component of equilibrium tide (meters)",
          "title": "Lunar Component M",
          "type": "number"
        },
        "note": {
          "description": "Explanatory note",
          "title": "Note",
          "type": "string"
        },
        "solar_component_m": {
          "description": "Solar component of equilibrium tide (meters)",
          "title": "Solar Component M",
          "type": "number"
        }
      },
      "required": [
        "lunar_component_m",
        "solar_component_m",
        "combined_m",
        "note"
      ],
      "title": "EquilibriumTide",
      "type": "object"
    },
    "ForcingIndices": {
      "properties": {
        "diurnal_class": {
          "description": "Tidal regime classification",
          "title": "Diurnal Class",
          "type": "string"
        },
        "diurnal_inequality": {
          "description": "Diurnal inequality value",
          "title": "Diurnal Inequality",
          "type": "number"
        },
        "king_tide_risk": {
          "description": "King tide risk score (0 to 1)",
          "title": "King Tide Risk",
          "type": "number"
        },
        "perigee_proximity": {
          "description": "Perigee proximity score (0 to 1)",
          "title": "Perigee Proximity",
          "type": "number"
        },
        "spring_neap_index": {
          "description": "Spring-neap index (-1 to +1)",
          "title": "Spring Neap Index",
          "type": "number"
        },
        "syzygy_status": {
          "description": "Syzygy status",
          "title": "Syzygy Status",
          "type": "string"
        },
        "total_forcing": {
          "description": "Total tidal forcing score",
          "title": "Total Forcing",
          "type": "number"
        }
      },
      "required": [
        "spring_neap_index",
        "syzygy_status",
        "diurnal_inequality",
        "diurnal_class",
        "total_forcing",
        "king_tide_risk",
        "perigee_proximity"
      ],
      "title": "ForcingIndices",
      "type": "object"
    },
    "LunarApsis": {
      "description": "One lunar perigee (closest approach) or apogee (farthest point): the instant the Moon's geocentric distance is at its minimum or maximum, found from DE440 to about a second.",
      "properties": {
        "distance_km": {
          "description": "Geometric Earth-Moon centre-to-centre distance at the apsis, km.",
          "format": "double",
          "type": "number"
        },
        "time": {
          "description": "Instant of the apsis, ISO-8601 with the UTC offset of the response's timezone.",
          "format": "date-time",
          "type": "string"
        },
        "type": {
          "description": "perigee or apogee (stable id).",
          "enum": [
            "perigee",
            "apogee"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "time",
        "distance_km"
      ],
      "title": "LunarApsis",
      "type": "object"
    },
    "LunarSyzygy": {
      "description": "A New or Full Moon with the Moon's distance and its supermoon / micromoon class under the requested supermoon_definition.",
      "properties": {
        "distance_class": {
          "description": "supermoon (relative_distance >= 0.9), micromoon (<= 0.1) or regular.",
          "enum": [
            "supermoon",
            "micromoon",
            "regular"
          ],
          "type": "string"
        },
        "distance_km": {
          "description": "Geometric Earth-Moon centre-to-centre distance at that instant, km.",
          "format": "double",
          "type": "number"
        },
        "phase": {
          "description": "new_moon or full_moon (stable id).",
          "enum": [
            "new_moon",
            "full_moon"
          ],
          "type": "string"
        },
        "reference_apogee": {
          "$ref": "#/$defs/LunarApsis"
        },
        "reference_perigee": {
          "$ref": "#/$defs/LunarApsis"
        },
        "relative_distance": {
          "description": "(Da - D) / (Da - Dp): 1 at perigee distance, 0 at apogee distance, against reference_apogee and reference_perigee.",
          "format": "double",
          "type": "number"
        },
        "time": {
          "description": "Instant of the New or Full Moon (geocentric, apparent longitudes), ISO-8601 with the UTC offset of the response's timezone.",
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "phase",
        "time",
        "distance_km",
        "relative_distance",
        "distance_class",
        "reference_perigee",
        "reference_apogee"
      ],
      "title": "LunarSyzygy",
      "type": "object"
    },
    "Observer": {
      "properties": {
        "lat": {
          "description": "Observer latitude",
          "title": "Lat",
          "type": "number"
        },
        "lon": {
          "description": "Observer longitude",
          "title": "Lon",
          "type": "number"
        }
      },
      "required": [
        "lat",
        "lon"
      ],
      "title": "Observer",
      "type": "object"
    },
    "TidalLunarData": {
      "properties": {
        "days_to_perigee": {
          "description": "Whole days (rounded) to the next perigee; next_perigee has the exact instant.",
          "title": "Days To Perigee",
          "type": "integer"
        },
        "declination": {
          "description": "Moon declination in degrees",
          "title": "Declination",
          "type": "number"
        },
        "distance_anomaly": {
          "description": "Distance anomaly (perigee proximity)",
          "title": "Distance Anomaly",
          "type": "number"
        },
        "distance_km": {
          "description": "Moon distance in km",
          "title": "Distance Km",
          "type": "number"
        },
        "geocentric_distance_km": {
          "description": "Geometric Earth-Moon centre-to-centre distance, km (distance_km is from the observer).",
          "format": "double",
          "type": "number"
        },
        "next_apogee": {
          "$ref": "#/$defs/LunarApsis"
        },
        "next_perigean_spring_tide": {
          "allOf": [
            {
              "$ref": "#/$defs/LunarSyzygy"
            }
          ],
          "description": "The next New or Full Moon within 90% of perigee (a supermoon under orbit_90): the syzygy behind a perigean spring ('king') tide. Astronomical forcing only; local tide height depends on the coast."
        },
        "next_perigee": {
          "$ref": "#/$defs/LunarApsis"
        },
        "perigee_status": {
          "description": "From the Moon's geocentric distance between the nearest perigee and apogee (relative_distance): 'near_perigee' at 0.9 or more, 'near_apogee' at 0.1 or less, else 'intermediate'. The same 90% rule as a supermoon (orbit_90).",
          "title": "Perigee Status",
          "type": "string"
        },
        "phase_angle": {
          "description": "Lunar phase angle in degrees",
          "title": "Phase Angle",
          "type": "number"
        },
        "phase_name": {
          "description": "Lunar phase name",
          "title": "Phase Name",
          "type": "string"
        },
        "previous_apogee": {
          "$ref": "#/$defs/LunarApsis"
        },
        "previous_perigee": {
          "$ref": "#/$defs/LunarApsis"
        },
        "relative_distance": {
          "description": "(Da - D) / (Da - Dp) against the perigee and apogee nearest in time: 1 at perigee, 0 at apogee.",
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "phase_name",
        "phase_angle",
        "distance_km",
        "distance_anomaly",
        "declination",
        "perigee_status",
        "days_to_perigee"
      ],
      "title": "TidalLunarData",
      "type": "object"
    },
    "TidalMeta": {
      "properties": {
        "calculation_ms": {
          "description": "Calculation time in milliseconds",
          "title": "Calculation Ms",
          "type": "integer"
        },
        "calculation_type": {
          "description": "Type of calculation performed",
          "title": "Calculation Type",
          "type": "string"
        },
        "disclaimer": {
          "description": "Disclaimer about astronomical vs local predictions",
          "title": "Disclaimer",
          "type": "string"
        },
        "ephemeris": {
          "description": "Ephemeris used, e.g., 'DE440'",
          "title": "Ephemeris",
          "type": "string"
        }
      },
      "required": [
        "ephemeris",
        "calculation_type",
        "disclaimer",
        "calculation_ms"
      ],
      "title": "TidalMeta",
      "type": "object"
    },
    "TidalSolarData": {
      "properties": {
        "declination": {
          "description": "Sun declination in degrees",
          "title": "Declination",
          "type": "number"
        },
        "distance_au": {
          "description": "Sun distance in AU",
          "title": "Distance Au",
          "type": "number"
        }
      },
      "required": [
        "declination",
        "distance_au"
      ],
      "title": "TidalSolarData",
      "type": "object"
    }
  }
}