.svg){kind=icon}
.svg){kind=icon}
What you get with the Astronomy API
Most “astronomy API” use cases boil down to two things: solar events (sunrise/sunset) and solar position (where the sun is in the sky). This API gives you both—so you can trigger automations, power solar-aware features, and plan ahead with consistent outputs.
Sunrise & sunset in local time
Receive ISO timestamps with timezone offsets so your UI can render immediately without extra conversion logic.
Solar azimuth and solar elevation for the current hour
Get solar geometry outputs in degrees for the coordinates you care about—useful for solar energy, outdoor UX, and sun-direction features.
Historical + planning window support
Query historical timestamps and pull a multi-day forward view (30-day forecast per your spec) for scheduling, analytics, and planning workflows.
Bulk-friendly
Request multiple locations in a single call (per your spec) so production systems can batch updates.
Timezone flexibility
Use timezone auto-detection from coordinates or pass the timezone explicitly
What you get with the Astronomy API
Most “astronomy API” use cases boil down to two things: solar events (sunrise/sunset) and solar position (where the sun is in the sky). This API gives you both—so you can trigger automations, power solar-aware features, and plan ahead with consistent outputs.
{
"message": "success",
"data": [
{
"lat": 12,
"lng": 77,
"timezone": "Asia/Kolkata",
"timestamp": "2026-03-24T05:00:00.000Z",
"solar_azimuth": 108.22,
"solar_elevation": 58.51,
"sunrise": "2026-03-24T06:24:33+05:30",
"sunset": "2026-03-24T18:33:16+05:30"
}
]
}
"message": "success",
"data": [
{
"lat": 12,
"lng": 77,
"timezone": "Asia/Kolkata",
"timestamp": "2026-03-24T05:00:00.000Z",
"solar_azimuth": 108.22,
"solar_elevation": 58.51,
"sunrise": "2026-03-24T06:24:33+05:30",
"sunset": "2026-03-24T18:33:16+05:30"
}
]
}
TUTORIALS
How to get started with Ambee’s air quality API
Here’s how you can get started with the Astronomy API in just a few clicks-
Step 1: Sign up and generate your API key from the dashboard.
Step 2: Copy your API key (you’ll use it in the x-api-key header).
Step 3: Make your first call using latitude/longitude (and optionally timezone).
Step 4: Move from a single-location test to bulk requests as you scale.
Step 1: Sign up and generate your API key from the dashboard.
Step 2: Copy your API key (you’ll use it in the x-api-key header).
Step 3: Make your first call using latitude/longitude (and optionally timezone).
Step 4: Move from a single-location test to bulk requests as you scale.
Response parameters
message
Request status (e.g., success))
data
Array of results (supports bulk patterns)
lat, lng
Coordinates for the returned record
timezone
IANA timezone (auto-detected or user-provided, per your spec)
solar_azimuth
The UTC timestamp for the “current hour” record
solar_elevation
Sun direction angle (degrees)
sunrise, sunset
Sun height angle above/below the horizon (degrees)
If you want one clarifying line that reduces support load, add this directly under the list: A common industry definition treats sunrise/sunset using standardized astronomical conventions with refraction approximations.
HTML Code Editor
Copy Code
Copied
What you get with the Astronomy API
Most “astronomy API” use cases boil down to two things: solar events (sunrise/sunset) and solar position (where the sun is in the sky). This API gives you both—so you can trigger automations, power solar-aware features, and plan ahead with consistent outputs.
Base URL:
Latest (current hour)
GET /astronomy/latest/by-lat-lng?lat={lat}&lng={lng}
Headers: x-api-key: YOUR_API_KEY
Optional: timezone={IANA timezone}
History (time range)
GET /astronomy/history/by-lat-lng?lat={lat}&lng={lng}&from=YYYY-MM-DD hh:mm:ss&to=YYYY-MM-DD hh:mm:ss
Headers: x-api-key: YOUR_API_KEY
Optional: timezone={IANA timezone}
Forecast (planning window)
GET /astronomy/forecast/by-lat-lng?lat={lat}&lng={lng}&days=30
Headers: x-api-key: YOUR_API_KEY
Optional: timezone={IANA timezone}
Bulk (multiple locations in one request)
POST /astronomy/bulk
Headers: x-api-key: YOUR_API_KEY
Content-Type: application/json
Body: { "locations": [ { "lat": 12, "lng": 77, "timezone": "Asia/Kolkata" }, ... ] }
Minimal curl example
curl --request GET \
--url "https://api.ambeedata.com/astronomy/latest/by-lat-lng?lat=12&lng=77" \
--header "x-api-key: YOUR_API_KEY" \
--header "Content-Type: application/json"
Node.js example
const https = require("https");
const options = {
method: "GET",
hostname: "api.ambeedata.com",
path: "/astronomy/latest/by-lat-lng?lat=12&lng=77",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-type": "application/json"
}
};
const req = https.request(options, (res) => {
const chunks = [];
res.on("data", (chunk) => chunks.push(chunk));
res.on("end", () => console.log(Buffer.concat(chunks).toString()));
});
req.end();
Response status codes and error handling
200 OK: Success: response contains astronomy data.
400 Bad Request: Missing/malformed parameters (check lat/lng ranges and date formats).
401 Unauthorized: Missing/invalid API key.
403 Forbidden: Key doesn’t have permission for the resource.
404 Not Found: Wrong endpoint path.
500 Internal Server Error: Server issue; retry with backoff.
400 Bad Request: Missing/malformed parameters (check lat/lng ranges and date formats).
401 Unauthorized: Missing/invalid API key.
403 Forbidden: Key doesn’t have permission for the resource.
404 Not Found: Wrong endpoint path.
500 Internal Server Error: Server issue; retry with backoff.
Use cases and examples
Solar-aware products often depend on the sun’s position for orientation logic (azimuth tracking is a well-known concept in solar tracking systems), and major weather platforms explicitly market sunrise/sunset and sun data for energy planning.
This API supports use cases such as:
Renewables & energy
Align solar features, dashboards, and planning workflows with sunrise/sunset and current-hour solar geometry.
Smart home and IoT
Trigger routines at sunset/sunrise
Mobility & logistics
Add day/night context for routes, ETAs, and operational planning.
Outdoor, photography, travel
Provide location-based sunrise/sunset times; pair with weather APIs for “conditions at sunrise” style experiences that other platforms explicitly demonstrate.
Analytics & research
Programmatically retrieve sun event times and solar angle features for modeling and reporting.
Frequently asked questions
What is an astronomy API?
An astronomy API typically provides astronomical events (like sunrise and sunset) and/or positions (like azimuth/elevation/altitude) for a location and time.
Does this API return sunrise/sunset in local time or UTC?
This Astronomy API is designed to return sunrise and sunset as local-time ISO timestamps (with timezone offset) per your product spec; many competing “sun parameters” APIs return sunrise/sunset in UTC by default, which shifts conversion effort to the developer.
What’s the difference between solar azimuth and solar elevation?
Azimuth describes the sun’s compass direction, and elevation describes how high the sun is above (or below) the horizon; these angles are standard outputs in astronomy/solar position systems.
Can I request historical data?
Yes—historical access is a standard expectation in astronomy APIs and is explicitly supported by major providers (and is included in your product spec).
How far ahead can I query?
Multi-day astronomy ranges vary across providers (for example, next 60 days or about a month per request are common patterns); your product spec supports a 30‑day forecast window.
How do I authenticate?
Use your API key via the x-api-key request header, consistent with Ambee’s other APIs.