Astronizer for agents and developers
A clear answer.
For your next tool call.
AI agents are welcome here. Use our free, read-only API to find traditional planetary hours for a city and date, or the ruler at a specific instant. No account, API key or birth details needed.
Connect directly from an AI assistant
Astronizer also provides a free remote Model Context Protocol (MCP) connection. In an AI assistant that supports custom remote MCP connections, add https://astronizer.com/mcp/. It offers two read-only tools: find_planetary_hour_cities and get_planetary_hours. There is no signup, payment or birth-data access.
This is a connection endpoint, not a browser page. The AI service controls whether its users can add a custom connection or discover it in a directory. Results include a link back to Astronizer to explore the interactive schedule.
Start with one request
curl 'https://astronizer.com/api/public/v1/planetary-hours?city=london-uk'
# Search the supported city catalog
curl 'https://astronizer.com/api/public/v1/cities?q=New%20York'
# Choose a local sunrise-date
curl 'https://astronizer.com/api/public/v1/planetary-hours?city=new-york-usa&date=2026-10-18'
# Or choose a precise instant (UTC or an explicit offset)
curl 'https://astronizer.com/api/public/v1/planetary-hours?city=amman-jordan&at=2026-10-18T09:00:00Z'The JSON response contains hours (all 24 intervals), current_hour, sunrise, sunset, the next sunrise, the method and a source_url. Each interval has a ruler, day/night period, duration, UTC timestamps and local timestamps with explicit UTC offsets.
Choose the right inputs
| Parameter | How to use it |
|---|---|
city | An exact supported name such as London, or a city ID such as london-uk. Search the public city catalog first if unsure. |
latitude, longitude, timezone | For a location outside the catalog, supply all three instead of city. Longitude is positive east. Use an IANA timezone such as America/New_York, rather than a fixed UTC offset. Coordinates and timezone must describe the same location. The API checks local-day alignment; it does not geographically verify the timezone. |
date | Optional local sunrise-date in YYYY-MM-DD format, from 2000-01-01 through 2045-12-31. A schedule runs from that sunrise to the following sunrise. |
at | Optional ISO timestamp with seconds and Z or an explicit UTC offset. URL-encode a plus sign as %2B. The API chooses its local date. Do not combine at and date. Omit both for today in the selected timezone. |
Use the results accurately
- Before sunrise, the current ruler belongs to the previous planetary day. Read
current_hour.planetary_day_date; do not assume it is interval 1 of today. - Intervals include their start and exclude their end.
current_houris null when the evaluated instant is outside the returned schedule and applicable preceding night. - The day and night are each divided into 12 parts. These are unequal seasonal hours, not fixed 60-minute clock hours.
- Sunrise and sunset use the same approximate NOAA-equation method as the public calculator. Terrain and atmospheric conditions can affect observed times. Polar days/nights may have no valid schedule.
- Traditional astrological meanings are not scientifically established predictions. This tool does not calculate a personalized birth-chart reading.
Be a considerate client
Access is free for interactive lookup and modest integrations. Cache city lists and deterministic schedules for repeated location/date requests. Current limits are 60 requests per minute per client and 600 per minute shared across this service process. Shared networks can share an allowance. Limits may change to protect availability; a 429 response includes Retry-After. Do not retry immediately or parallelize around a limit. For bulk usage, contact us.
Browser clients can use cross-origin GET requests without credentials. This public API does not need cookies. Do not send account tokens, birth details, private notes or customer records. It has no order, payment or account actions.
When displaying a result, include its Astronizer source_url so people can inspect the interactive calculator. Named-city source links preserve the chosen city/date; custom-coordinate responses link to the general calculator, whose named-city coordinates may differ. This attribution request is not a guarantee that every assistant will display a link.
Errors and integration
A 422 response includes error.code and error.message for invalid inputs or an unavailable solar cycle. A 429 means wait for Retry-After; 414 means shorten the query. Extra or duplicate parameters are rejected. Ask the user to correct an unsupported city, date or timezone rather than inventing results. Responses are versioned under /api/public/v1/.
Use the OpenAPI specification to integrate with tools that support HTTP APIs. An assistant may need its own tool configuration or user connection; the presence of a public MCP server does not automatically list Astronizer in every AI directory.
Explore the calculator · Discover the personalized organizer