freehoroscopeAPI
Developer documentation

Build with
FreeHoroscopeAPI.

Find the parameters, examples and response fields for each API. All public data endpoints use GET and return JSON. No API key is required.

Open API Playground OpenAPI JSON

Use the playground's Reference tab for all allowed values, defaults and nested response fields.

Daily, Weekly and Monthly Horoscopes.

Choose a zodiac sign and get a reading. Try each endpoint in the API Explorer.

API v1

Daily Horoscope

Every day
GET/api/v1/get-horoscope/daily

A fresh perspective for today. Get the daily horoscope for any zodiac sign.

ParameterRequiredDescription
signYesZodiac sign, e.g. aquarius
https://freehoroscopeapi.com/api/v1/get-horoscope/daily?sign=aquarius

Weekly Horoscope

Every week
GET/api/v1/get-horoscope/weekly

The bigger picture. Get the horoscope for the current week.

ParameterRequiredDescription
signYesZodiac sign, e.g. scorpio
https://freehoroscopeapi.com/api/v1/get-horoscope/weekly?sign=scorpio

Monthly Horoscope

Every month
GET/api/v1/get-horoscope/monthly

Look a little further ahead with a horoscope for the current month.

ParameterRequiredDescription
signYesZodiac sign, e.g. scorpio
https://freehoroscopeapi.com/api/v1/get-horoscope/monthly?sign=scorpio
Response Format & Supported Parameters

All horoscope endpoints return a data object containing date, period, sign, and horoscope. The period is daily, weekly, or monthly.

Pass one of the 12 supported signs as the required sign query parameter. Values are case-insensitive. A missing or invalid sign returns HTTP 400. An upstream failure or invalid response returns HTTP 502. A timeout returns HTTP 504. See API errors and time limits.

{
  "data": {
    "date": "2026-09-29",
    "period": "daily",
    "sign": "Aries",
    "horoscope": "..."
  }
}

Astrology API: Planetary Positions and Panchang

Get calculated planetary positions, daily Panchang, and local Sun and Moon times. Start with the free astrology API examples.

API v1

Planetary Positions

GET/api/v1/planetary-positions

Positions, zodiac signs, speeds and retrograde flags for 12 bodies, including mean Rahu and Ketu. Sidereal results include nakshatra and pada.

Parameters and Response
ParameterDescription
datetimeOptional ISO-8601 timestamp with seconds and Z or a UTC offset. Defaults to now.
zodiacsidereal (default, approximate Lahiri) or tropical.
lat, lngOptional coordinate pair. Adds location and timezone.
includeobserver adds altitude, azimuth and distance. Requires coordinates.

Response fields include datetime, zodiac, ayanamsa, engine and bodies. Positions use Earth's center. Observer data is separate.

Supported instants: 1900-01-01 through before 2053-01-01 UTC. Encode + in UTC offsets as %2B.

https://freehoroscopeapi.com/api/v1/planetary-positions?zodiac=sidereal
Try Planetary Positions ↗

Daily Panchang

GET/api/v1/panchang

Tithi, nakshatra, yoga, karana and weekday for a location. See the value at the start of the day and each transition time.

Parameters and Response
ParameterDescription
lat, lngRequired latitude and longitude. Longitude aliases: lon, long.
dateOptional YYYY-MM-DD. Defaults to today in the location's timezone.

Response fields include date, location, timezone, window, day_basis, weekday, conventions, tithi, nakshatra, yoga and karana. Each limb has at_start and transitions. Tithi also includes paksha.

The day runs from sunrise to the next sunrise. If sunrise is unavailable, day_basis identifies a local civil-day fallback. The model uses approximate Lahiri calculations; festival and regional observance rules are not included.

https://freehoroscopeapi.com/api/v1/panchang?lat=19.076&lng=72.878
Try Daily Panchang ↗

Sun, Moon & Rahu Kaal

GET/api/v1/times

Sunrise, sunset, moonrise, moonset, Moon phase and Rahu Kaal. Add precise Moon illumination for the selected local date.

Parameters and Response
ParameterDescription
lat, lngRequired coordinate pair. Longitude aliases: lon, long.
dateOptional YYYY-MM-DD. Defaults to local today.
timeformat12 (default, AM/PM) or 24 (ISO-8601).
includemoon_details adds Moon illumination and phase angle at local noon.

Response fields include date, location, timezone, sun, moon and rahukaalam. Sun data includes daylight, twilight and photography periods.

Requests without a date also include today and tomorrow. Unavailable events may be null or include an error.

https://freehoroscopeapi.com/api/v1/times?lat=19.076&lng=72.878&timeformat=24
Try Sun & Moon Times ↗

Each endpoint returns the original SunMoonTracker JSON fields, without a data wrapper. Invalid parameters return HTTP 400 or 422. If the service is unavailable, the response is HTTP 502 or 503. Coordinates use latitude −90 to 90 and longitude −180 to 180.

Connect an AI agent.

Use MCP tools, the API contract, or the public skill. No API key or account is required.

Connect with MCP

Use an MCP client to call six read-only tools for horoscopes, planetary positions, Panchang, Sun and Moon times, and tarot.

Follow the MCP connection guide to add the server to your client and list its tools.

Build with REST

Use the OpenAPI contract to find each endpoint, its inputs, and its response fields. An agent can use it to construct GET requests.

Use the API Playground to test a request and inspect its result.

Use the API skill

Give the public SKILL.md URL to an agent that supports skills. It explains which API to use, how to set inputs, and how to handle results.

It covers REST requests, MCP tools, response formats, and attribution.

Find the service automatically

These files let software discover the API and its agent tools.

The digest is a hash of the skill file. Before you load the skill, calculate the SHA-256 hash of the downloaded bytes. Compare it with the part after sha256: in the index's digest value.

The homepage also returns discovery addresses in Link response headers. Software can read them before it processes the page content.

Read documentation as Markdown

Send Accept: text/markdown to get the page text, links, and examples without the HTML layout. A normal browser request returns HTML.

Example request:

curl -H 'Accept: text/markdown' 'https://freehoroscopeapi.com/docs'

API errors and time limits

Use the HTTP status and the error code to handle failed requests.

Errors generated by this API contain an error message and a stable code. Errors are not cached and can be read by browser clients.

  • 400: missing_sign, invalid_sign, or invalid_count. Correct the query parameter.
  • 405: method_not_allowed. Use GET or OPTIONS.
  • 502: upstream_unavailable or invalid_upstream_response. Retry later.
  • 503: service_not_configured. Contact support.
  • 504: upstream_timeout. Retry later.

Horoscope calls have a 10-second limit. Calculation calls have a 30-second limit. Each limit includes the full response body. Responses must be JSON and must not exceed 1 MiB. Successful data is checked against the OpenAPI schemas. Invalid data returns 502.

Horoscope checks include the requested sign and period, a non-empty reading, and a valid date or month. The date is the provider's reading label; these checks do not guarantee freshness.

Calculation service errors keep their status and structured JSON body. Parameter errors can use a detail array with HTTP 422. Correct these parameters before you retry. For 502 or 504, use a limited number of retries with increasing delays.

{
  "error": "The upstream service took too long to respond. Try again later.",
  "code": "upstream_timeout"
}