{
  "openapi": "3.1.0",
  "info": {
    "title": "Astronomy API",
    "version": "1.0.0",
    "description": "Sunrise, sunset, twilight, golden hour, moon phase and moonrise for any coordinates and date, computed in-worker.\n\nSun and moon, computed for any point on Earth and any date: sunrise, sunset, solar noon, day length, civil/nautical/astronomical twilight, the golden-hour window photographers plan around, live solar position (azimuth and elevation), moonrise and moonset, moon phase with its name and illumination percentage, lunar distance, and the dates of the next full and new moon. Pure computation with the standard astronomical algorithms — no upstream services, no rate-limited providers, answers in milliseconds at the lowest token cost. Accuracy is almanac-grade: New York''s 2026 summer-solstice sunrise lands within a minute of the published time, the equator gets its 12.1-hour equinox day, Tromso correctly reports polar night in January and midnight sun in June, and the computed next new and full moons match the real 2026 lunar calendar to the day. The almanac endpoint returns up to 31 days of combined sun and moon data in one call. Built for photography and drone apps (golden hour), fitness and outdoor products, agriculture, astronomy and stargazing tools, religious observance apps, and smart-home automations.",
    "contact": {
      "name": "Data and APIs",
      "url": "https://dataandapis.com/contact"
    },
    "termsOfService": "https://dataandapis.com/terms-of-service",
    "license": {
      "name": "Data and APIs Terms of Service",
      "url": "https://dataandapis.com/terms-of-service"
    },
    "x-logo": {
      "url": "https://dataandapis.com/images/astronomy.webp"
    }
  },
  "externalDocs": {
    "description": "Documentation, live tester and pricing",
    "url": "https://dataandapis.com/apis/astronomy"
  },
  "servers": [
    {
      "url": "https://api-astronomy.dataandapis.com"
    }
  ],
  "tags": [
    {
      "name": "Data",
      "description": "Astronomy API belongs to the Data category of the Data and APIs catalog."
    }
  ],
  "paths": {
    "/v1/moon": {
      "get": {
        "operationId": "moonPhaseTimes",
        "summary": "Moon Phase & Times",
        "description": "Moon Phase & Times endpoint of the Astronomy API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/astronomy/moon-phase-times"
        },
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-09-05"
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "51.5"
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "-0.12"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "lat": 51.5,
                  "lon": -0.12,
                  "date": "2026-09-05",
                  "phase": {
                    "value": 0.796,
                    "name": "Waning Crescent",
                    "illumination_pct": 35.8,
                    "next_full_moon": "2026-09-26",
                    "next_new_moon": "2026-09-11"
                  },
                  "times_utc": {
                    "moonrise": "2026-09-05T22:45:58Z",
                    "moonset": "2026-09-05T15:54:55Z",
                    "always_up": false,
                    "always_down": false
                  },
                  "position_now": {
                    "at": "2026-09-05T12:00:00Z",
                    "azimuth_deg": 277.41,
                    "elevation_deg": 30.62,
                    "distance_km": 364096
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/almanac": {
      "get": {
        "operationId": "multiDayAlmanac",
        "summary": "Multi-Day Almanac",
        "description": "Multi-Day Almanac endpoint of the Astronomy API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/astronomy/multi-day-almanac"
        },
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-09-05"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "7"
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "34.05"
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "-118.24"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "lat": 34.05,
                  "lon": -118.24,
                  "days": 7,
                  "count": 7,
                  "results": [
                    {
                      "date": "2026-09-05",
                      "sun": {
                        "solar_noon": "2026-09-05T19:53:09Z",
                        "sunrise": "2026-09-05T13:30:44Z",
                        "sunset": "2026-09-06T02:15:34Z",
                        "civil_twilight_begin": "2026-09-05T13:05:21Z",
                        "civil_twilight_end": "2026-09-06T02:40:56Z",
                        "nautical_twilight_begin": "2026-09-05T12:35:25Z",
                        "nautical_twilight_end": "2026-09-06T03:10:52Z",
                        "astronomical_twilight_begin": "2026-09-05T12:04:45Z",
                        "astronomical_twilight_end": "2026-09-06T03:41:33Z",
                        "golden_hour_morning_end": "2026-09-05T14:03:56Z",
                        "golden_hour_evening_begin": "2026-09-06T01:42:22Z",
                        "day_length_seconds": 45890,
                        "polar": null
                      },
                      "moon": {
                        "moonrise": "2026-09-05T07:17:26Z",
                        "moonset": "2026-09-05T22:41:46Z",
                        "always_up": false,
                        "always_down": false,
                        "phase": 0.796,
                        "phase_name": "Waning Crescent",
                        "illumination_pct": 35.8
                      }
                    },
                    {
                      "date": "2026-09-06",
                      "sun": {
                        "solar_noon": "2026-09-06T19:52:48Z",
                        "sunrise": "2026-09-06T13:31:25Z",
                        "sunset": "2026-09-07T02:14:12Z",
                        "civil_twilight_begin": "2026-09-06T13:06:05Z",
                        "civil_twilight_end": "2026-09-07T02:39:32Z",
                        "nautical_twilight_begin": "2026-09-06T12:36:12Z",
                        "nautical_twilight_end": "2026-09-07T03:09:24Z",
                        "astronomical_twilight_begin": "2026-09-06T12:05:37Z",
                        "astronomical_twilight_end": "2026-09-07T03:39:59Z",
                        "golden_hour_morning_end": "2026-09-06T14:04:35Z",
                        "golden_hour_evening_begin": "2026-09-07T01:41:01Z",
                        "day_length_seconds": 45767,
                        "polar": null
                      },
                      "moon": {
                        "moonrise": "2026-09-06T08:26:00Z",
                        "moonset": "2026-09-06T23:36:05Z",
                        "always_up": false,
                        "always_down": false,
                        "phase": 0.834,
                        "phase_name": "Waning Crescent",
                        "illumination_pct": 24.9
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/sun": {
      "get": {
        "operationId": "sunTimesPosition",
        "summary": "Sun Times & Position",
        "description": "Sun Times & Position endpoint of the Astronomy API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/astronomy/sun-times-position"
        },
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-06-21"
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "40.7128"
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "-74.006"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "lat": 40.7128,
                  "lon": -74.006,
                  "date": "2026-06-21",
                  "times_utc": {
                    "solar_noon": "2026-06-21T16:59:03Z",
                    "sunrise": "2026-06-21T09:26:14Z",
                    "sunset": "2026-06-22T00:31:52Z",
                    "civil_twilight_begin": "2026-06-21T08:52:49Z",
                    "civil_twilight_end": "2026-06-22T01:05:18Z",
                    "nautical_twilight_begin": "2026-06-21T08:10:09Z",
                    "nautical_twilight_end": "2026-06-22T01:47:57Z",
                    "astronomical_twilight_begin": "2026-06-21T07:19:44Z",
                    "astronomical_twilight_end": "2026-06-22T02:38:22Z",
                    "golden_hour_morning_end": "2026-06-21T10:07:34Z",
                    "golden_hour_evening_begin": "2026-06-21T23:50:33Z",
                    "day_length_seconds": 54338,
                    "polar": null
                  },
                  "position_now": {
                    "at": "2026-06-21T12:00:00Z",
                    "azimuth_deg": 80.9,
                    "elevation_deg": 26.44
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 1 token per call."
      }
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ]
}