freehoroscopeAPIModel Context Protocol
Connect your
AI assistant.
Use six tools to get horoscope, astronomy, Panchang and tarot data. The server is public. An API key is not required.
Connect an MCP client
- Add a remote MCP server in your client.
- Enter the server URL below.
- Select Streamable HTTP if the client asks for a transport. Select no authentication.
- Connect and load the tool list.
https://freehoroscopeapi.com/mcpThe endpoint accepts MCP requests with HTTP POST. Open this guide in your browser. The endpoint URL does not display a web page.
Example request: “Get Sun and Moon times for Mumbai on 2026-10-01. Use latitude 19.076 and longitude 72.878. Include Moon illumination.”
{"name":"get_sun_moon_times","arguments":{"lat":19.076,"lng":72.878,"date":"2026-10-01","timeformat":"24","include":["moon_details"]}}Available tools
Open a tool to see its inputs, allowed values, defaults and response schema. The schemas use the same definitions as the API playground.
For coordinates, use lat and lng. The service selects the timezone. For optional inputs, omit the field to use its default.
Get horoscope · get_horoscope
Get a daily, weekly or monthly horoscope. The default period is daily. Returns the REST response with its data wrapper.
| Input | Values | Details |
|---|---|---|
signRequired | string Allowed: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces | Zodiac sign. Use one of the listed lowercase values. |
periodOptional | string Allowed: daily, weekly, monthly Default: "daily" | The requested reading period: daily, weekly or monthly. |
Complete input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"sign": {
"type": "string",
"enum": [
"aries",
"taurus",
"gemini",
"cancer",
"leo",
"virgo",
"libra",
"scorpio",
"sagittarius",
"capricorn",
"aquarius",
"pisces"
],
"description": "Zodiac sign. Use one of the listed lowercase values.",
"examples": [
"aries"
]
},
"period": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly"
],
"description": "The requested reading period: daily, weekly or monthly.",
"default": "daily"
}
},
"required": [
"sign"
],
"additionalProperties": false
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"data": {
"description": "The horoscope reading for the requested sign and period.",
"allOf": [
{
"$ref": "#/$defs/Horoscope"
}
]
}
},
"required": [
"data"
],
"description": "A data object wraps the horoscope reading.",
"$defs": {
"Horoscope": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Reading date or period label. Daily and weekly readings use YYYY-MM-DD; monthly readings use YYYY-MM. Do not assume every value is a full date.",
"examples": [
"2026-10"
]
},
"period": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly"
],
"description": "The requested reading period: daily, weekly or monthly."
},
"sign": {
"type": "string",
"description": "The requested zodiac sign. Case-insensitive when checked against the request.",
"examples": [
"Aries"
],
"minLength": 1
},
"horoscope": {
"type": "string",
"description": "Written reading returned by the horoscope provider.",
"minLength": 1,
"pattern": "\\S"
}
},
"required": [
"date",
"period",
"sign",
"horoscope"
],
"oneOf": [
{
"properties": {
"period": {
"type": "string",
"enum": [
"monthly"
]
},
"date": {
"type": "string",
"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$"
}
}
},
{
"properties": {
"period": {
"type": "string",
"enum": [
"daily",
"weekly"
]
},
"date": {
"type": "string",
"format": "date",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
}
}
}
]
}
}
}Get planetary positions · get_planetary_positions
Returns calculated planetary positions, not written horoscope readings. No data wrapper. All 12 bodies are included. Coordinates are optional but must be supplied as a pair. Sidereal output uses an approximate Lahiri model, with mean Rahu and Ketu. No houses or Ascendant are returned. The complete upstream body is checked against the response schema before it is returned. The total upstream deadline is 30 seconds. The timezone is derived from the coordinates and returned in the response; a timezone query parameter cannot override it.
| Input | Values | Details |
|---|---|---|
datetimeOptional | string | Defaults to the current instant. Supply ISO-8601 with seconds and Z or an explicit UTC offset. Supported UTC instants: 1900-01-01 inclusive to 2053-01-01 exclusive. Fractional seconds may have up to six digits. Date-only values, missing offsets, leap seconds and -00:00 are rejected. URL-encode a positive offset sign as %2B. Coordinates do not infer the input timezone. |
zodiacOptional | string Allowed: sidereal, tropical Default: "sidereal" | Sidereal uses an approximate Lahiri model. Tropical results omit nakshatra and pada and return a null ayanamsa. |
latOptional | number Minimum: -90 Maximum: 90 | Latitude in degrees. For planetary positions, omit both coordinates or supply latitude and one longitude. Required when include=observer. |
lngOptional | number Minimum: -180 Maximum: 180 | Longitude in degrees. Supply lng with lat. MCP uses lng only; lon and long are REST aliases. |
includeOptional | array Allowed: observer Default: [] | Add observer positions for the ten physical bodies: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto. Includes altitude_deg, azimuth_deg, distance_km and above_horizon. Rahu and Ketu are not physical bodies. Requires lat and one of lng, lon or long. The geocentric bodies object is unchanged. This endpoint accepts only observer. Omit include or send an empty value for the standard response. The parameter is a comma-separated list; whitespace and duplicate entries are ignored. Unknown values return HTTP 400. For MCP, supply a JSON array of the allowed values, not a comma-separated string. |
Complete input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "Defaults to the current instant. Supply ISO-8601 with seconds and Z or an explicit UTC offset. Supported UTC instants: 1900-01-01 inclusive to 2053-01-01 exclusive. Fractional seconds may have up to six digits. Date-only values, missing offsets, leap seconds and -00:00 are rejected. URL-encode a positive offset sign as %2B. Coordinates do not infer the input timezone.",
"examples": [
"2000-01-01T12:00:00Z"
]
},
"zodiac": {
"type": "string",
"enum": [
"sidereal",
"tropical"
],
"default": "sidereal",
"description": "Sidereal uses an approximate Lahiri model. Tropical results omit nakshatra and pada and return a null ayanamsa.",
"examples": [
"sidereal"
]
},
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in degrees. For planetary positions, omit both coordinates or supply latitude and one longitude. Required when include=observer.",
"examples": [
19.076
]
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in degrees. Supply lng with lat. MCP uses lng only; lon and long are REST aliases.",
"examples": [
72.878
]
},
"include": {
"type": "array",
"items": {
"type": "string",
"enum": [
"observer"
]
},
"default": [],
"description": "Add observer positions for the ten physical bodies: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto. Includes altitude_deg, azimuth_deg, distance_km and above_horizon. Rahu and Ketu are not physical bodies. Requires lat and one of lng, lon or long. The geocentric bodies object is unchanged. This endpoint accepts only observer. Omit include or send an empty value for the standard response. The parameter is a comma-separated list; whitespace and duplicate entries are ignored. Unknown values return HTTP 400. For MCP, supply a JSON array of the allowed values, not a comma-separated string.",
"examples": [
[
"observer"
]
]
}
},
"required": [],
"additionalProperties": false,
"dependentRequired": {
"lat": [
"lng"
],
"lng": [
"lat"
]
},
"allOf": [
{
"if": {
"required": [
"include"
],
"properties": {
"include": {
"contains": {
"const": "observer"
}
}
}
},
"then": {
"required": [
"lat",
"lng"
]
}
}
]
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "Resolved instant in UTC."
},
"zodiac": {
"type": "string",
"enum": [
"sidereal",
"tropical"
],
"description": "Resolved zodiac system."
},
"ayanamsa": {
"$ref": "#/$defs/Ayanamsa"
},
"node_convention": {
"type": "string",
"enum": [
"mean"
],
"description": "Lunar node convention. The API uses mean nodes."
},
"reference_frame": {
"type": "string",
"description": "Reference frame for the geocentric positions."
},
"units": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Units for each numeric position field."
},
"engine": {
"$ref": "#/$defs/CalculationEngine"
},
"bodies": {
"type": "object",
"properties": {
"sun": {
"$ref": "#/$defs/PlanetaryBody"
},
"moon": {
"$ref": "#/$defs/PlanetaryBody"
},
"mercury": {
"$ref": "#/$defs/PlanetaryBody"
},
"venus": {
"$ref": "#/$defs/PlanetaryBody"
},
"mars": {
"$ref": "#/$defs/PlanetaryBody"
},
"jupiter": {
"$ref": "#/$defs/PlanetaryBody"
},
"saturn": {
"$ref": "#/$defs/PlanetaryBody"
},
"uranus": {
"$ref": "#/$defs/PlanetaryBody"
},
"neptune": {
"$ref": "#/$defs/PlanetaryBody"
},
"pluto": {
"$ref": "#/$defs/PlanetaryBody"
},
"rahu": {
"$ref": "#/$defs/PlanetaryBody"
},
"ketu": {
"$ref": "#/$defs/PlanetaryBody"
}
},
"required": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto",
"rahu",
"ketu"
],
"description": "All 12 bodies are always present: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Rahu and Ketu. No include parameter is needed for outer planets."
},
"location": {
"$ref": "#/$defs/Location"
},
"timezone": {
"type": "string",
"description": "IANA timezone identifier derived from the coordinates, for example Asia/Kolkata, Europe/London or America/New_York. UTC is the fallback if no timezone is found. The value can be any timezone returned by the location database; it is not a fixed list. timezone is a response field, not a supported query parameter. Local dates and event offsets follow this timezone, including daylight saving time where applicable. Present only when coordinates are supplied; it does not change the UTC datetime or geocentric positions.",
"examples": [
"Asia/Kolkata"
],
"readOnly": true
},
"observer": {
"$ref": "#/$defs/Observer"
}
},
"required": [
"datetime",
"zodiac",
"ayanamsa",
"node_convention",
"reference_frame",
"units",
"engine",
"bodies"
],
"description": "Calculated positions at one instant. There is no data wrapper. location and timezone appear only with coordinates; observer appears only with include=observer.",
"$defs": {
"Ayanamsa": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the sidereal offset model."
},
"model": {
"type": "string",
"description": "Calculation convention used to approximate the offset."
},
"degrees": {
"type": "number",
"description": "Offset applied to tropical longitude, in degrees."
}
},
"required": [
"name",
"model",
"degrees"
],
"description": "Applied sidereal offset. Null for tropical positions."
},
{
"type": "null"
}
]
},
"CalculationEngine": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Calculation library."
},
"version": {
"type": "string",
"description": "Library version."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris dataset used for the calculation."
},
"timescale": {
"type": "string",
"description": "Timescale used internally."
},
"supported_start": {
"type": "string",
"format": "date-time",
"description": "First supported UTC instant, inclusive."
},
"supported_end_exclusive": {
"type": "string",
"format": "date-time",
"description": "Upper UTC bound, excluded from the supported interval."
},
"outer_planet_targets": {
"type": "string",
"description": "Targets used for outer-planet positions."
},
"node_model": {
"type": "string",
"description": "Model for the mean lunar nodes Rahu and Ketu."
},
"speed_method": {
"type": "string",
"description": "Method used to calculate longitude speed."
}
},
"required": [
"name",
"version",
"ephemeris",
"supported_start",
"supported_end_exclusive"
]
},
"PlanetaryBody": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"luminary",
"planet",
"dwarf_planet",
"lunar_node"
],
"description": "Body classification."
},
"longitude": {
"type": "number",
"minimum": 0,
"maximum": 360,
"description": "Degrees in the selected zodiac, from 0 inclusive to 360 exclusive."
},
"latitude": {
"type": "number",
"description": "Ecliptic latitude in degrees; zero for lunar nodes."
},
"longitude_speed": {
"type": "number",
"description": "Degrees per TT day in the selected zodiac."
},
"retrograde": {
"type": "boolean",
"description": "True when longitude_speed is negative in the selected zodiac."
},
"sign": {
"type": "string",
"enum": [
"Aries",
"Taurus",
"Gemini",
"Cancer",
"Leo",
"Virgo",
"Libra",
"Scorpio",
"Sagittarius",
"Capricorn",
"Aquarius",
"Pisces"
],
"description": "Zodiac sign containing the selected longitude."
},
"degrees_in_sign": {
"type": "number",
"minimum": 0,
"maximum": 30,
"description": "From 0 inclusive to 30 exclusive."
},
"nakshatra": {
"type": "string",
"description": "Present only for sidereal positions."
},
"pada": {
"type": "integer",
"minimum": 1,
"maximum": 4,
"description": "Present only for sidereal positions."
}
},
"required": [
"type",
"longitude",
"latitude",
"longitude_speed",
"retrograde",
"sign",
"degrees_in_sign"
]
},
"Location": {
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in degrees north of the equator; negative values are south."
},
"lon": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in degrees east of Greenwich; negative values are west. The response always uses lon, regardless of the request alias."
}
},
"required": [
"lat",
"lon"
],
"description": "Responses use lon even when the request uses lng or long."
},
"Observer": {
"type": "object",
"properties": {
"reference_frame": {
"type": "string",
"description": "Reference frame for the topocentric positions."
},
"azimuth_convention": {
"type": "string",
"description": "Direction and origin of the azimuth measurement."
},
"horizon_deg": {
"type": "number",
"description": "Horizon altitude used for above_horizon, in degrees."
},
"elevation_m": {
"type": "number",
"description": "Assumed observer elevation, in metres. This API does not accept an elevation parameter."
},
"bodies": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/ObserverBody"
},
"description": "The ten physical bodies; Rahu and Ketu are excluded."
}
},
"required": [
"reference_frame",
"azimuth_convention",
"horizon_deg",
"elevation_m",
"bodies"
],
"description": "Optional topocentric data, present only with include=observer and coordinates. Geometric body-center altitudes exclude atmospheric refraction."
},
"ObserverBody": {
"type": "object",
"properties": {
"altitude_deg": {
"type": "number",
"description": "Geometric altitude of the body center, without refraction."
},
"azimuth_deg": {
"type": "number",
"description": "Degrees clockwise from true north."
},
"distance_km": {
"type": "number",
"minimum": 0,
"description": "Distance from the observer to the body, in kilometres."
},
"above_horizon": {
"type": "boolean",
"description": "True when the geometric body-center altitude is above the horizon."
}
},
"required": [
"altitude_deg",
"azimuth_deg",
"distance_km",
"above_horizon"
]
}
}
}Get Panchang · get_panchang
Requires lat and one of lng, lon or long. The date defaults to local today. The window runs from sunrise to the next sunrise, with a labeled civil-day fallback if sunrise is unavailable. The entire calculation window must fall within 1900-01-01T00:00:00Z inclusive to 2053-01-01T00:00:00Z exclusive. Returns astronomical limbs using an approximate Lahiri model; festival and regional observance rules are not included. No data wrapper. The complete upstream body is checked against the response schema before it is returned. The total upstream deadline is 30 seconds. The timezone is derived from the coordinates and returned in the response; a timezone query parameter cannot override it. This endpoint has no include or timeformat parameter. Window and transition timestamps always use ISO-8601 with local UTC offsets. The service derives the timezone from lat and lng, with UTC as a fallback. Timezone is a response field, not an input. Omit date for local today. The response has no data wrapper.
| Input | Values | Details |
|---|---|---|
latRequired | number Minimum: -90 Maximum: 90 | Latitude in degrees. Also supply lng, lon or long. |
lngRequired | number Minimum: -180 Maximum: 180 | Longitude in degrees. Supply lng with lat. MCP uses lng only; lon and long are REST aliases. |
dateOptional | string | Local calendar date in YYYY-MM-DD format. Omit the parameter or leave it empty to use today in the timezone derived from the coordinates. Panchang uses the date to select sunrise through the next sunrise. For Sun and Moon times, an explicit date omits the live today and tomorrow summaries. For MCP, omit date to use the default; empty strings are not accepted. |
Complete input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in degrees. Also supply lng, lon or long.",
"examples": [
19.076
]
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in degrees. Supply lng with lat. MCP uses lng only; lon and long are REST aliases.",
"examples": [
72.878
]
},
"date": {
"type": "string",
"format": "date",
"description": "Local calendar date in YYYY-MM-DD format. Omit the parameter or leave it empty to use today in the timezone derived from the coordinates. Panchang uses the date to select sunrise through the next sunrise. For Sun and Moon times, an explicit date omits the live today and tomorrow summaries. For MCP, omit date to use the default; empty strings are not accepted.",
"examples": [
"2026-10-01"
]
}
},
"required": [
"lat",
"lng"
],
"additionalProperties": false
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Resolved local calendar date."
},
"location": {
"$ref": "#/$defs/Location"
},
"timezone": {
"type": "string",
"description": "IANA timezone identifier derived from the coordinates, for example Asia/Kolkata, Europe/London or America/New_York. UTC is the fallback if no timezone is found. The value can be any timezone returned by the location database; it is not a fixed list. timezone is a response field, not a supported query parameter. Local dates and event offsets follow this timezone, including daylight saving time where applicable.",
"examples": [
"Asia/Kolkata"
],
"readOnly": true
},
"window": {
"$ref": "#/$defs/CalendarWindow"
},
"day_basis": {
"type": "string",
"enum": [
"sunrise_to_next_sunrise",
"civil_day_fallback_no_sunrise"
],
"description": "sunrise_to_next_sunrise uses consecutive local sunrises. civil_day_fallback_no_sunrise uses local midnight to midnight when sunrise is unavailable."
},
"weekday": {
"type": "string",
"description": "English weekday name for the requested local date.",
"examples": [
"Thursday"
]
},
"tithi": {
"$ref": "#/$defs/TithiLimb"
},
"nakshatra": {
"$ref": "#/$defs/NakshatraLimb"
},
"yoga": {
"$ref": "#/$defs/YogaLimb"
},
"karana": {
"$ref": "#/$defs/KaranaLimb"
},
"conventions": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Calculation conventions for ayanamsa, positions, tithi, nakshatra, yoga, karana and scope."
}
},
"required": [
"date",
"location",
"timezone",
"window",
"day_basis",
"weekday",
"tithi",
"nakshatra",
"yoga",
"karana",
"conventions"
],
"description": "Daily astronomical Panchang, with each limb evaluated at the window start and all transitions inside the window. There is no data wrapper.",
"$defs": {
"Location": {
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in degrees north of the equator; negative values are south."
},
"lon": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in degrees east of Greenwich; negative values are west. The response always uses lon, regardless of the request alias."
}
},
"required": [
"lat",
"lon"
],
"description": "Responses use lon even when the request uses lng or long."
},
"CalendarWindow": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time",
"description": "Inclusive start of the calculation window, in ISO-8601 with local UTC offset."
},
"end": {
"type": "string",
"format": "date-time",
"description": "Exclusive end of the calculation window, in ISO-8601 with local UTC offset."
},
"end_exclusive": {
"type": "boolean",
"enum": [
true
],
"description": "Always true. A transition at end belongs to the next window."
}
},
"required": [
"start",
"end",
"end_exclusive"
]
},
"TithiLimb": {
"type": "object",
"properties": {
"at_start": {
"$ref": "#/$defs/TithiValue"
},
"transitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "Transition instant, in ISO-8601 with local UTC offset."
},
"to": {
"$ref": "#/$defs/TithiValue"
}
},
"required": [
"datetime",
"to"
]
},
"description": "Transitions inside [window.start, window.end). An empty array means the value does not change in this window."
}
},
"required": [
"at_start",
"transitions"
],
"description": "Value at the start of the calculation window, followed by transitions in time order."
},
"TithiValue": {
"type": "object",
"properties": {
"number": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"description": "Tithi number from 1 to 30."
},
"name": {
"type": "string",
"description": "Tithi name, including Purnima or Amavasya at the end of each half."
},
"paksha": {
"type": "string",
"enum": [
"Shukla",
"Krishna"
],
"description": "Shukla for the waxing half; Krishna for the waning half."
}
},
"required": [
"number",
"name",
"paksha"
]
},
"NakshatraLimb": {
"type": "object",
"properties": {
"at_start": {
"$ref": "#/$defs/NakshatraValue"
},
"transitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "Transition instant, in ISO-8601 with local UTC offset."
},
"to": {
"$ref": "#/$defs/NakshatraValue"
}
},
"required": [
"datetime",
"to"
]
},
"description": "Transitions inside [window.start, window.end). An empty array means the value does not change in this window."
}
},
"required": [
"at_start",
"transitions"
],
"description": "Value at the start of the calculation window, followed by transitions in time order."
},
"NakshatraValue": {
"type": "object",
"properties": {
"number": {
"type": "integer",
"minimum": 1,
"maximum": 27,
"description": "Nakshatra index from 1 to 27."
},
"name": {
"type": "string",
"description": "Name of the sidereal lunar mansion."
}
},
"required": [
"number",
"name"
]
},
"YogaLimb": {
"type": "object",
"properties": {
"at_start": {
"$ref": "#/$defs/YogaValue"
},
"transitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "Transition instant, in ISO-8601 with local UTC offset."
},
"to": {
"$ref": "#/$defs/YogaValue"
}
},
"required": [
"datetime",
"to"
]
},
"description": "Transitions inside [window.start, window.end). An empty array means the value does not change in this window."
}
},
"required": [
"at_start",
"transitions"
],
"description": "Value at the start of the calculation window, followed by transitions in time order."
},
"YogaValue": {
"type": "object",
"properties": {
"number": {
"type": "integer",
"minimum": 1,
"maximum": 27,
"description": "Yoga index from 1 to 27."
},
"name": {
"type": "string",
"description": "Yoga name from the sidereal Sun-plus-Moon longitude."
}
},
"required": [
"number",
"name"
]
},
"KaranaLimb": {
"type": "object",
"properties": {
"at_start": {
"$ref": "#/$defs/KaranaValue"
},
"transitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"datetime": {
"type": "string",
"format": "date-time",
"description": "Transition instant, in ISO-8601 with local UTC offset."
},
"to": {
"$ref": "#/$defs/KaranaValue"
}
},
"required": [
"datetime",
"to"
]
},
"description": "Transitions inside [window.start, window.end). An empty array means the value does not change in this window."
}
},
"required": [
"at_start",
"transitions"
],
"description": "Value at the start of the calculation window, followed by transitions in time order."
},
"KaranaValue": {
"type": "object",
"properties": {
"number": {
"type": "integer",
"minimum": 1,
"maximum": 60,
"description": "Half-tithi index from 1 to 60."
},
"name": {
"type": "string",
"description": "Karana name for the half-tithi."
}
},
"required": [
"number",
"name"
]
}
}
}Get Sun and Moon times · get_sun_moon_times
Requires lat and one of lng, lon or long. Defaults to local today and 12-hour event strings. Set timeformat=24 for ISO-8601 event timestamps. With no date parameter, available today/tomorrow summaries are also included. Events can be null at polar locations, and Rahu Kaal can be absent. include=moon_details adds a separate local-noon calculation. No data wrapper. The complete upstream body is checked against the response schema before it is returned. The total upstream deadline is 30 seconds. The timezone is derived from the coordinates and returned in the response; a timezone query parameter cannot override it. The service derives the timezone from lat and lng, with UTC as a fallback. Timezone is a response field, not an input. Omit date for local today. The response has no data wrapper.
| Input | Values | Details |
|---|---|---|
latRequired | number Minimum: -90 Maximum: 90 | Latitude in degrees. Also supply lng, lon or long. |
lngRequired | number Minimum: -180 Maximum: 180 | Longitude in degrees. Supply lng with lat. MCP uses lng only; lon and long are REST aliases. |
dateOptional | string | Local calendar date in YYYY-MM-DD format. Omit the parameter or leave it empty to use today in the timezone derived from the coordinates. Panchang uses the date to select sunrise through the next sunrise. For Sun and Moon times, an explicit date omits the live today and tomorrow summaries. For MCP, omit date to use the default; empty strings are not accepted. |
timeformatOptional | string Allowed: 12, 24 Default: "12" | Event time display. Use 12 for YYYY-MM-DDThh:mm:ss AM/PM ±HHMM (for example, 2026-10-01T06:30:00 AM +0530). Use 24 for ISO-8601 with the local UTC offset (for example, 2026-10-01T06:30:00+05:30). The short sunrise and sunset values in today/tomorrow use h:mm AM/PM or HH:mm. moon.details.evaluated_at always uses ISO-8601. Only the exact strings 12 and 24 are accepted. |
includeOptional | array Allowed: moon_details Default: [] | Add moon.details with illumination_pct, phase_angle_deg, evaluated_at and status. The calculation uses local noon on the selected date, not the current time. evaluated_at is always ISO-8601, independent of timeformat. Outside the supported UTC interval from 1900-01-01 inclusive to 2053-01-01 exclusive, illumination_pct and phase_angle_deg are null and status is outside_supported_range. This endpoint accepts only moon_details. Omit include or send an empty value for the standard response. The parameter is a comma-separated list; whitespace and duplicate entries are ignored. Unknown values return HTTP 400. For MCP, supply a JSON array of the allowed values, not a comma-separated string. |
Complete input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in degrees. Also supply lng, lon or long.",
"examples": [
19.076
]
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in degrees. Supply lng with lat. MCP uses lng only; lon and long are REST aliases.",
"examples": [
72.878
]
},
"date": {
"type": "string",
"format": "date",
"description": "Local calendar date in YYYY-MM-DD format. Omit the parameter or leave it empty to use today in the timezone derived from the coordinates. Panchang uses the date to select sunrise through the next sunrise. For Sun and Moon times, an explicit date omits the live today and tomorrow summaries. For MCP, omit date to use the default; empty strings are not accepted.",
"examples": [
"2026-10-01"
]
},
"timeformat": {
"type": "string",
"enum": [
"12",
"24"
],
"default": "12",
"description": "Event time display. Use 12 for YYYY-MM-DDThh:mm:ss AM/PM ±HHMM (for example, 2026-10-01T06:30:00 AM +0530). Use 24 for ISO-8601 with the local UTC offset (for example, 2026-10-01T06:30:00+05:30). The short sunrise and sunset values in today/tomorrow use h:mm AM/PM or HH:mm. moon.details.evaluated_at always uses ISO-8601. Only the exact strings 12 and 24 are accepted.",
"examples": [
"24"
]
},
"include": {
"type": "array",
"items": {
"type": "string",
"enum": [
"moon_details"
]
},
"default": [],
"description": "Add moon.details with illumination_pct, phase_angle_deg, evaluated_at and status. The calculation uses local noon on the selected date, not the current time. evaluated_at is always ISO-8601, independent of timeformat. Outside the supported UTC interval from 1900-01-01 inclusive to 2053-01-01 exclusive, illumination_pct and phase_angle_deg are null and status is outside_supported_range. This endpoint accepts only moon_details. Omit include or send an empty value for the standard response. The parameter is a comma-separated list; whitespace and duplicate entries are ignored. Unknown values return HTTP 400. For MCP, supply a JSON array of the allowed values, not a comma-separated string.",
"examples": [
[
"moon_details"
]
]
}
},
"required": [
"lat",
"lng"
],
"additionalProperties": false
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Resolved local calendar date for the requested coordinates.",
"examples": [
"2026-10-01"
]
},
"location": {
"$ref": "#/$defs/Location"
},
"timezone": {
"type": "string",
"description": "IANA timezone identifier derived from the coordinates, for example Asia/Kolkata, Europe/London or America/New_York. UTC is the fallback if no timezone is found. The value can be any timezone returned by the location database; it is not a fixed list. timezone is a response field, not a supported query parameter. Local dates and event offsets follow this timezone, including daylight saving time where applicable.",
"examples": [
"Asia/Kolkata"
],
"readOnly": true
},
"sun": {
"$ref": "#/$defs/Sun"
},
"moon": {
"$ref": "#/$defs/Moon"
},
"rahukaalam": {
"$ref": "#/$defs/TimePeriod"
},
"today": {
"$ref": "#/$defs/TodaySummary"
},
"tomorrow": {
"$ref": "#/$defs/TomorrowSummary"
}
},
"required": [
"date",
"location",
"timezone",
"sun",
"moon"
],
"description": "No data wrapper. Rahu Kaal and some periods can be absent where the needed Sun events do not occur.",
"$defs": {
"Location": {
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in degrees north of the equator; negative values are south."
},
"lon": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in degrees east of Greenwich; negative values are west. The response always uses lon, regardless of the request alias."
}
},
"required": [
"lat",
"lon"
],
"description": "Responses use lon even when the request uses lng or long."
},
"Sun": {
"type": "object",
"properties": {
"events": {
"$ref": "#/$defs/SunEvents"
},
"daylight": {
"$ref": "#/$defs/Daylight"
},
"twilight_periods": {
"type": "object",
"properties": {
"civil": {
"$ref": "#/$defs/TwilightMorningEvening"
},
"nautical": {
"$ref": "#/$defs/TwilightMorningEvening"
},
"astronomical": {
"$ref": "#/$defs/TwilightMorningEvening"
}
},
"required": [
"civil",
"nautical",
"astronomical"
],
"description": "Civil, nautical and astronomical twilight intervals, each with morning/evening bounds and a status."
},
"twilight": {
"$ref": "#/$defs/MorningEvening"
},
"photography": {
"type": "object",
"properties": {
"golden_hour": {
"$ref": "#/$defs/MorningEvening"
},
"blue_hour": {
"$ref": "#/$defs/MorningEvening"
}
},
"description": "Available golden_hour and blue_hour intervals. A period is omitted if its required crossings do not occur."
}
},
"required": [
"events",
"daylight",
"twilight_periods"
],
"description": "Sun events, daylight duration and available twilight and photography periods."
},
"SunEvents": {
"type": "object",
"properties": {
"dawn": {
"$ref": "#/$defs/EventTime"
},
"sunrise": {
"$ref": "#/$defs/EventTime"
},
"noon": {
"$ref": "#/$defs/EventTime"
},
"sunset": {
"$ref": "#/$defs/EventTime"
},
"dusk": {
"$ref": "#/$defs/EventTime"
},
"error": {
"type": "string",
"description": "Present when some events are unavailable."
}
},
"required": [
"dawn",
"sunrise",
"noon",
"sunset",
"dusk"
]
},
"EventTime": {
"anyOf": [
{
"type": "string",
"description": "Event timestamp in the local timezone. timeformat=12 returns YYYY-MM-DDThh:mm:ss AM/PM ±HHMM; timeformat=24 returns ISO-8601 with an offset. Null when the event does not occur. The default 12-hour string is not RFC 3339."
},
{
"type": "null"
}
]
},
"Daylight": {
"type": "object",
"properties": {
"duration_seconds": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Total daylight during the local calendar day, in seconds. Null when unavailable."
},
{
"type": "null"
}
]
},
"change_from_yesterday_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Difference from the previous local day, in seconds. Negative means a shorter day. Null when unavailable."
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"normal",
"polar_day",
"polar_night",
"unavailable"
],
"description": "normal for a day with crossings, polar_day for continuous daylight, polar_night for continuous darkness, or unavailable when the duration cannot be calculated."
}
},
"required": [
"duration_seconds",
"change_from_yesterday_seconds",
"status"
]
},
"TwilightMorningEvening": {
"type": "object",
"properties": {
"morning": {
"$ref": "#/$defs/TwilightPeriod"
},
"evening": {
"$ref": "#/$defs/TwilightPeriod"
}
},
"required": [
"morning",
"evening"
]
},
"TwilightPeriod": {
"type": "object",
"properties": {
"start": {
"$ref": "#/$defs/EventTime"
},
"end": {
"$ref": "#/$defs/EventTime"
},
"status": {
"type": "string",
"enum": [
"ok",
"no_crossing"
],
"description": "ok when both crossings occur; no_crossing when the requested twilight boundary is not crossed."
}
},
"required": [
"start",
"end",
"status"
]
},
"MorningEvening": {
"type": "object",
"properties": {
"morning": {
"$ref": "#/$defs/TimePeriod"
},
"evening": {
"$ref": "#/$defs/TimePeriod"
}
},
"required": [
"morning",
"evening"
]
},
"TimePeriod": {
"type": "object",
"properties": {
"start": {
"$ref": "#/$defs/EventTime"
},
"end": {
"$ref": "#/$defs/EventTime"
}
},
"required": [
"start",
"end"
]
},
"Moon": {
"type": "object",
"properties": {
"moonrise": {
"$ref": "#/$defs/EventTime"
},
"moonset": {
"$ref": "#/$defs/EventTime"
},
"phase_value": {
"type": "number",
"description": "Astral phase value, approximately 0 to 28; not illumination percent."
},
"phase_description": {
"type": "string",
"description": "Readable Moon phase name associated with phase_value.",
"examples": [
"Waxing Gibbous"
]
},
"error": {
"type": "string",
"description": "Calculation message when one or more Moon events are unavailable. Independently available fields remain present."
},
"details": {
"$ref": "#/$defs/MoonDetails"
}
},
"required": [
"moonrise",
"moonset",
"phase_value",
"phase_description"
],
"description": "Moonrise, moonset and approximate phase, with optional precise Moon details."
},
"MoonDetails": {
"type": "object",
"properties": {
"evaluated_at": {
"type": "string",
"format": "date-time",
"description": "Local noon on the requested date, always ISO-8601."
},
"status": {
"type": "string",
"enum": [
"ok",
"outside_supported_range"
],
"description": "ok when calculated, or outside_supported_range when local noon falls outside the supported UTC interval."
},
"illumination_pct": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Illuminated portion of the Moon, from 0 to 100 percent. Null outside the supported interval."
},
{
"type": "null"
}
]
},
"phase_angle_deg": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 360,
"description": "Sun–Moon ecliptic longitude separation, from 0 to 360 degrees. Null outside the supported interval."
},
{
"type": "null"
}
]
}
},
"required": [
"evaluated_at",
"status",
"illumination_pct",
"phase_angle_deg"
],
"description": "Optional Moon calculation, present only with include=moon_details. Evaluated at local noon on the requested date."
},
"TodaySummary": {
"type": "object",
"properties": {
"day_progress_pct": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Rounded percentage of the sunrise-to-sunset interval already elapsed, clamped to 0–100. Null when the required events are unavailable."
},
{
"type": "null"
}
]
},
"daylight_remaining_seconds": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Daylight remaining from the request time until the end of the local day, in seconds. Null when unavailable."
},
{
"type": "null"
}
]
},
"sunrise": {
"anyOf": [
{
"type": "string",
"description": "Short local clock time: h:mm AM/PM for timeformat=12, or HH:mm for timeformat=24. No date or UTC offset is included. Null when the event is unavailable.",
"examples": [
"06:30"
]
},
{
"type": "null"
}
]
},
"sunset": {
"anyOf": [
{
"type": "string",
"description": "Short local clock time: h:mm AM/PM for timeformat=12, or HH:mm for timeformat=24. No date or UTC offset is included. Null when the event is unavailable.",
"examples": [
"06:30"
]
},
{
"type": "null"
}
]
}
},
"required": [
"day_progress_pct",
"daylight_remaining_seconds",
"sunrise",
"sunset"
],
"description": "Present when date is omitted and the summary is available. Sunrise and sunset use short clock times."
},
"TomorrowSummary": {
"type": "object",
"properties": {
"sunrise": {
"anyOf": [
{
"type": "string",
"description": "Short local clock time: h:mm AM/PM for timeformat=12, or HH:mm for timeformat=24. No date or UTC offset is included. Null when the event is unavailable.",
"examples": [
"06:30"
]
},
{
"type": "null"
}
]
},
"sunset": {
"anyOf": [
{
"type": "string",
"description": "Short local clock time: h:mm AM/PM for timeformat=12, or HH:mm for timeformat=24. No date or UTC offset is included. Null when the event is unavailable.",
"examples": [
"06:30"
]
},
{
"type": "null"
}
]
}
},
"required": [
"sunrise",
"sunset"
],
"description": "Present when date is omitted and the summary is available. Sunrise and sunset use short clock times."
}
}
}List tarot cards · list_tarot_cards
List tarot card names, meanings and descriptions. Select all, major or minor arcana. No pagination.
| Input | Values | Details |
|---|---|---|
arcanaOptional | string Allowed: all, major, minor Default: "all" | Select all 78 cards, the 22 major arcana cards, or the 56 minor arcana cards. |
Complete input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"arcana": {
"type": "string",
"enum": [
"all",
"major",
"minor"
],
"default": "all",
"description": "Select all 78 cards, the 22 major arcana cards, or the 56 minor arcana cards."
}
},
"required": [],
"additionalProperties": false
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"nhits": {
"type": "integer",
"minimum": 1,
"maximum": 78,
"description": "Number of cards returned. This equals the length of cards."
},
"cards": {
"type": "array",
"items": {
"$ref": "#/$defs/TarotCard"
},
"minItems": 1,
"maxItems": 78,
"description": "Returned tarot cards. List endpoints return the selected complete deck. The random endpoint returns distinct cards from its selected pool."
}
},
"required": [
"nhits",
"cards"
],
"description": "nhits and cards are top-level fields. There is no data wrapper.",
"$defs": {
"TarotCard": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"major",
"minor"
],
"description": "Arcana group: major or minor."
},
"name": {
"type": "string",
"description": "Full card name.",
"examples": [
"The Fool"
]
},
"name_short": {
"type": "string",
"description": "Short card identifier, for example ar00.",
"examples": [
"ar00"
]
},
"value": {
"type": "string",
"description": "Card rank as a string."
},
"value_int": {
"type": "integer",
"description": "Card rank as an integer."
},
"meaning_up": {
"type": "string",
"description": "Upright meaning."
},
"meaning_rev": {
"type": "string",
"description": "Reversed meaning."
},
"desc": {
"type": "string",
"description": "Description of the card and its imagery."
},
"suit": {
"type": "string",
"enum": [
"wands",
"cups",
"swords",
"pentacles"
],
"description": "Present for minor arcana cards."
}
},
"required": [
"type",
"name",
"name_short",
"value",
"value_int",
"meaning_up",
"meaning_rev",
"desc"
]
}
}
}Draw tarot cards · draw_tarot_cards
Draws distinct random cards. The default pool is the 22 major arcana cards; use minor=true for all 78. Requests above the pool size return the complete pool. The response has nhits and cards at the top level, without a data wrapper. There is no include or timezone parameter.
| Input | Values | Details |
|---|---|---|
nOptional | integer Minimum: 1 Default: 1 | Requested number of distinct cards, as a positive base-10 integer. Default: 1. The response count is capped at the pool size: 22 when minor is false, or 78 when minor is true. For example, n=100 returns the complete selected pool. Zero, negative values and non-numeric values return HTTP 400. There is no pagination. |
minorOptional | boolean Default: false | Choose the random draw pool. The exact lowercase value true includes all 78 cards. false or an omitted parameter uses the 22 major arcana cards. The current API also treats other strings, including True and 1, as false; use true or false for portable requests. |
Complete input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"n": {
"type": "integer",
"minimum": 1,
"default": 1,
"description": "Requested number of distinct cards, as a positive base-10 integer. Default: 1. The response count is capped at the pool size: 22 when minor is false, or 78 when minor is true. For example, n=100 returns the complete selected pool. Zero, negative values and non-numeric values return HTTP 400. There is no pagination.",
"examples": [
3
]
},
"minor": {
"type": "boolean",
"default": false,
"description": "Choose the random draw pool. The exact lowercase value true includes all 78 cards. false or an omitted parameter uses the 22 major arcana cards. The current API also treats other strings, including True and 1, as false; use true or false for portable requests.",
"examples": [
false
]
}
},
"required": [],
"additionalProperties": false
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"nhits": {
"type": "integer",
"minimum": 1,
"maximum": 78,
"description": "Number of cards returned. This equals the length of cards."
},
"cards": {
"type": "array",
"items": {
"$ref": "#/$defs/TarotCard"
},
"minItems": 1,
"maxItems": 78,
"description": "Returned tarot cards. List endpoints return the selected complete deck. The random endpoint returns distinct cards from its selected pool."
}
},
"required": [
"nhits",
"cards"
],
"description": "nhits and cards are top-level fields. There is no data wrapper.",
"$defs": {
"TarotCard": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"major",
"minor"
],
"description": "Arcana group: major or minor."
},
"name": {
"type": "string",
"description": "Full card name.",
"examples": [
"The Fool"
]
},
"name_short": {
"type": "string",
"description": "Short card identifier, for example ar00.",
"examples": [
"ar00"
]
},
"value": {
"type": "string",
"description": "Card rank as a string."
},
"value_int": {
"type": "integer",
"description": "Card rank as an integer."
},
"meaning_up": {
"type": "string",
"description": "Upright meaning."
},
"meaning_rev": {
"type": "string",
"description": "Reversed meaning."
},
"desc": {
"type": "string",
"description": "Description of the card and its imagery."
},
"suit": {
"type": "string",
"enum": [
"wands",
"cups",
"swords",
"pentacles"
],
"description": "Present for minor arcana cards."
}
},
"required": [
"type",
"name",
"name_short",
"value",
"value_int",
"meaning_up",
"meaning_rev",
"desc"
]
}
}
}Responses and limits
Successful calls return structured JSON and the same JSON as text. Horoscope responses have a data wrapper. Tarot responses contain nhits and cards. Calculation responses have no wrapper.
Unavailable events can be null or contain an error. A failed tool call has isError: true and a text error with a status and code when available.
The server allows approximately 60 POST requests per minute, per client IP, at each Cloudflare location. Clients on the same network share this limit. HTTP 429 responses include Retry-After: 60. Request bodies must not exceed 64 KiB.
Horoscope requests have a 10-second service deadline. Calculation requests have a 30-second service deadline. The server does not store MCP sessions.
Follow the API usage terms. Include a visible “Powered by FreeHoroscopeAPI” link when you display the results.