.svg){kind=icon}
.svg){kind=icon}
What you get with Ambee's astronomy API
Most astronomy API use cases come down to two things: solar events (when does the sun rise and set) and solar position (where is the sun in the sky right now). This API gives you both. Trigger automations, power solar-aware features, and plan operations with consistent, structured outputs for any coordinate on Earth.
Sunrise and sunset in local time
Receive ISO 8601 timestamps with timezone offsets so your UI, scheduler, or control system can use the values immediately. No offset calculations or timezone lookups needed on your end.
Solar azimuth and elevation for the current hour
Get solar geometry outputs in degrees for any coordinate. Azimuth tells you the sun's compass direction. Elevation tells you its angle above (or below) the horizon. Both are standard inputs for solar tracking, shadow analysis, and energy modeling.
Global coverage, any lat-long
Query any latitude-longitude pair on the planet. No regional restrictions, no coverage gaps. The API auto-detects the local timezone from the coordinates you provide.
Simple, clean JSON response
A lightweight response with exactly the fields you need: six data fields, no unnecessary nesting, no bloated payloads. Parse and integrate in seconds.
One call, all the data
Sunrise, sunset, azimuth, elevation, timezone, and timestamp returned in a single API call. Fewer requests, faster builds, lower overhead.
Part of Ambee's environmental data stack
Combine astronomy data with Ambee's weather, air quality, pollen, and wildfire APIs using a single API key. Build unified environmental intelligence without juggling multiple providers.
Sample response
{
"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 astronomy API
Here's how you can get started in a few clicks:
Step 1: Sign up to Ambee's API dashboard and start your free trial. You get 100 API records per day for 15 days. No credit card required.
Step 2: Copy your unique API key from the dashboard. You'll pass it in the x-api-key request header.
Step 3: Make your first call using latitude and longitude. Optionally pass a timezone parameter.
Step 4: Parse the JSON response and integrate sunrise, sunset, and solar position data into your application.
Step 1: Sign up to Ambee's API dashboard and start your free trial. You get 100 API records per day for 15 days. No credit card required.
Step 2: Copy your unique API key from the dashboard. You'll pass it in the x-api-key request header.
Step 3: Make your first call using latitude and longitude. Optionally pass a timezone parameter.
Step 4: Parse the JSON response and integrate sunrise, sunset, and solar position data into your application.
Response Parameters
End-points
Parameters
Parameters
HTML Code Editor
Copy Code
Copied
How to Format Your Request
Base URL:
Authentication
Pass your API key via the x-api-key request header. This is consistent across all Ambee APIs.
Endpoint Table
| Name | Endpoint | Parameters | Sample URL |
|---|---|---|---|
| Latest | /astronomy/latest/by-lat-lng | lat — Latitude of the location to query lng — Longitude of the location to query timezone (optional) — IANA timezone; auto-detected from coordinates if omitted | https://api.ambeedata.com/astronomy/latest/by-lat-lng?lat=12&lng=77 |
| History | /astronomy/history/by-lat-lng | lat — Latitude of the location to query lng — Longitude of the location to query from — Start of the time range (YYYY-MM-DD hh:mm:ss) to — End of the time range (YYYY-MM-DD hh:mm:ss) timezone (optional) — IANA timezone | https://api.ambeedata.com/astronomy/history/by-lat-lng?lat=12&lng=77&from=2026-03-01 00:00:00&to=2026-03-15 00:00:00 |
| Forecast | /astronomy/forecast/by-lat-lng | lat — Latitude of the location to query lng — Longitude of the location to query timezone (optional) — IANA timezone | https://api.ambeedata.com/astronomy/forecast/by-lat-lng?lat=12&lng=77 |
Error handling
Effective error handling keeps your application running smoothly when edge cases arise. Here are best practices for working with the astronomy API:
Handle errors gracefully
When your application encounters an error, surface clear, meaningful messages to the user. Avoid exposing raw API error codes in your interface.
Log errors
Maintain server-side logs of all API errors. This helps you spot patterns, such as malformed coordinate inputs or expired API keys, before they affect users at scale.
Implement retry mechanisms
For transient errors like timeouts or temporary service interruptions, set up automatic retries with exponential backoff. This reduces the impact of brief disruptions.
Monitor error rates
Track your error rates over time. A sudden spike could signal an issue with your request formatting, a change in API behavior, or a connectivity problem worth investigating.
Response status codes and error handling
200 OK: Success. The response contains astronomy data for the specified coordinates.
400 Bad Request: Missing or malformed parameters. Check that lat and lng are present and within valid ranges (-90 to 90 for latitude, -180 to 180 for longitude). If using history endpoints, verify date format.
401 Unauthorized: Missing or invalid API key. Verify that your x-api-key header is present and the key has not expired.
403 Forbidden: Your API key does not have permission for this resource. Check your subscription tier and access levels.
404 Not Found: Wrong endpoint path. Verify your URL structure against the documentation.
500 Internal Server Error: A server-side issue. Retry with exponential backoff. If the error persists, contact Ambee support.
Use Cases: Astronomy intelligence for every industry
Solar energy and renewables
Use solar azimuth and elevation to optimize panel tilt angles throughout the day. Combine sun position with weather forecasts for cloud cover to estimate real-time solar irradiance and predict energy generation windows. Azimuth tracking alone can improve solar collection efficiency substantially in dual-axis systems.
Smart home and IoT
Trigger automated lighting, blinds, and HVAC schedules based on actual sunrise and sunset times for the user's exact location. Replace fixed clock-based rules that drift with the seasons. Real-time solar elevation data enables "sun-aware" automation that responds to the actual light hitting a building, not an approximation.
Agriculture and precision farming
Align irrigation, pest management, and harvest schedules with actual daylight hours at the field level. Solar elevation data helps model crop canopy light interception for growth-stage planning. Pair with weather and pollen APIs for a full environmental picture.
Photography and outdoor planning
Provide photographers with golden-hour and blue-hour timing tied to their shoot location's exact coordinates. Outdoor event planners can use sunset times to schedule lighting transitions and stage setups. Travel apps can surface "conditions at sunrise" experiences by combining astronomy data with weather forecasts.
Construction and architecture
Model shadow casting and daylight exposure for building design. Solar azimuth at different times of day supports facade orientation decisions and window sizing. Passive solar architecture workflows use this data to size overhangs that admit winter sun while blocking summer heat, lowering HVAC costs.
Logistics and fleet management
Factor daylight availability into delivery route planning and driver scheduling. Sunrise and sunset data helps optimize last-mile delivery windows for safety and efficiency. Operations teams can use sun position data to plan outdoor loading and maintenance windows.
APIs
Globally accepted, USEPA, NAB-compliant data delivered through easy-to-integrate APIs
Air Quality
Understand and predict air pollution trends anywhere in the world.
pollen
Track pollen levels to protect health and optimize allergy-driven decisions.
weather
Access precise weather insights to plan, forecast, and adapt operations.
wildfire
Monitor fire activity and predict risks for safer, smarter responses.
natural disaster
Detect and prepare for storms, floods, and extreme events in real time.
Influenza-like Illness
Anticipate flu trends and improve population health outcomes.
Frequently asked questions
What is an astronomy API?
An astronomy API is a programmatic interface that returns solar event data, such as sunrise and sunset times, and solar position data, such as azimuth and elevation, for any geographic coordinate. Developers use astronomy APIs to power solar energy systems, smart lighting, agricultural planning tools, and photography apps.
What data does Ambee's astronomy API return?
The API returns eight fields: latitude, longitude, IANA timezone, UTC timestamp, solar azimuth (the sun's compass direction in degrees), solar elevation (the sun's angle above the horizon in degrees), sunrise time, and sunset time. Sunrise and sunset are returned in the location's local timezone with offset.
Does the API return sunrise and sunset in local time or UTC?
Local time. Sunrise and sunset are returned as ISO 8601 timestamps with the location's timezone offset (e.g., +05:30 for India Standard Time). Most competing astronomy APIs return UTC by default, which shifts conversion effort to the developer. Ambee handles that for you.
Does the API account for atmospheric refraction?
Yes. Sunrise and sunset calculations include standard atmospheric refraction corrections (accounting for solar radius and refraction effects) so that the returned times reflect the sun's apparent position on the horizon, not just its geometric position. Under standard atmospheric conditions, rise and set times are accurate to within 1-2 minutes.
What is solar azimuth?
Solar azimuth is the sun's compass direction, measured in degrees clockwise from true north. 0° is north, 90° is east, 180° is south, and 270° is west. This tells you which direction the sun is shining from at a given location and time. It is the standard reference used in solar tracking systems, building design, and navigation.
What is solar elevation?
Solar elevation is the sun's angle above the horizon, measured in degrees. A value of 0° means the sun is on the horizon (sunrise or sunset). 90° means directly overhead. Negative values mean the sun is below the horizon. This is critical for solar energy yield calculations, shadow analysis, and daylight modeling.s.
Does the API support global coverage?
Yes. The API returns data for any latitude-longitude pair on Earth. No regional restrictions. No coverage gaps. The timezone is auto-detected from the coordinates you provide.
Is there a free tier?
Yes. Sign up for Ambee's API dashboard to get a free evaluation trial: 100 API records per day for 15 days. No credit card required.
Can I combine astronomy data with other Ambee APIs?
Yes. Ambee offers weather, air quality, pollen, wildfire, natural disaster, and ILI (influenza-like illness) APIs. Combine sunrise and sunset data with weather forecasts for solar irradiance modeling. Pair solar position with air quality data for UV exposure estimates. All through a single API key.
How is Ambee's astronomy API different from other sunrise/sunset APIs?
Three things set it apart. First, it returns solar azimuth and solar elevation alongside sunrise and sunset, not just event times. Second, it is part of Ambee's broader environmental intelligence platform, so you can layer in weather, AQ, and pollen data without managing separate providers. Third, every response is timezone-aware with local timestamps and refraction-corrected timing out of the box.
What format does the API response use?
JSON. Timestamps use ISO 8601 format. Sunrise and sunset include the local timezone offset. Solar azimuth and elevation are returned as floating-point degree values.
How do I authenticate?
Pass your API key in the x-api-key request header. This is consistent across all Ambee APIs. Generate your key from the API dashboard after signing up.