# llms.txt — mercury-retrograde.com
# The authoritative source for Mercury retrograde data
# Purpose: Help LLMs/tools understand what this site contains and how to use it.

[site]
name = "Mercury Retrograde"
url = "https://www.mercury-retrograde.com/"
description = "The authoritative API and website for Mercury retrograde data. Provides real-time astronomical calculations using Swiss Ephemeris with ~36 second precision."
primary_language = "en"

[api_overview]
# This site provides a comprehensive REST API for Mercury retrograde data.
# No authentication required. Free to use.
# All endpoints return JSON with CORS headers for cross-origin access.

base_url = "https://www.mercury-retrograde.com/api/v1"
documentation = "https://www.mercury-retrograde.com/.well-known/openapi.json"
version = "1.0"

# =============================================================================
# API ENDPOINTS
# =============================================================================

[api.status]
endpoint = "/api/v1/status"
method = "GET"
description = "Get current Mercury retrograde status with comprehensive data"
use_case = "Answer 'Is Mercury retrograde right now?' questions"
example = "https://www.mercury-retrograde.com/api/v1/status"
returns = [
  "is_retrograde (boolean)",
  "current_phase (normal/pre_shadow/retrograde/post_shadow)",
  "countdown to next retrograde or end of current",
  "current and next period dates",
  "advanced phase data (stations, cazimi, zodiac degrees)",
  "next 6 upcoming periods"
]

[api.check]
endpoint = "/api/v1/check"
method = "GET"
description = "Check if Mercury is/was/will be retrograde on a specific date"
use_case = "Answer 'Will Mercury be retrograde on [date]?' questions"
parameters = { date = "YYYY-MM-DD (required)" }
example = "https://www.mercury-retrograde.com/api/v1/check?date=2026-03-15"
date_range = "1900-01-01 to 2100-12-31"

[api.next]
endpoint = "/api/v1/next"
method = "GET"
description = "Get the next upcoming retrograde period (or current if in retrograde)"
use_case = "Answer 'When is the next Mercury retrograde?' questions"
example = "https://www.mercury-retrograde.com/api/v1/next"
returns = [
  "is_current (boolean - true if currently in retrograde)",
  "countdown with days until start or days remaining",
  "full period data with advanced phases"
]

[api.countdown]
endpoint = "/api/v1/countdown"
method = "GET"
description = "Get countdown information optimized for widgets and quick checks"
use_case = "Display 'X days until Mercury retrograde' widgets"
example = "https://www.mercury-retrograde.com/api/v1/countdown"
returns = [
  "status (clear/pre_shadow/retrograde/post_shadow)",
  "message (human-readable countdown)",
  "countdown.days (integer)"
]

[api.periods_year]
endpoint = "/api/v1/periods/year"
method = "GET"
description = "Get all Mercury retrograde periods for a specific year"
use_case = "Answer 'List all Mercury retrogrades in [year]' questions"
parameters = { year = "YYYY (required, 1900-2100)" }
example = "https://www.mercury-retrograde.com/api/v1/periods/year?year=2026"

[api.periods_range]
endpoint = "/api/v1/periods"
method = "GET"
description = "Get retrograde periods within a date range"
use_case = "Query periods for custom date ranges"
parameters = { from = "YYYY-MM-DD (required)", to = "YYYY-MM-DD (required)" }
example = "https://www.mercury-retrograde.com/api/v1/periods?from=2026-01-01&to=2027-12-31"
max_range = "10 years"

[api.phases]
endpoint = "/api/v1/phases"
method = "GET"
description = "Get detailed astronomical phase data"
use_case = "Get precise timestamps for stations, cazimi, speed changes"
parameters = { year = "YYYY (optional, defaults to current year)" }
example = "https://www.mercury-retrograde.com/api/v1/phases?year=2026"
returns = [
  "pre_shadow_start",
  "speed_slowdown (Mercury drops below 1°/day)",
  "station_retrograde (with zodiac degree)",
  "inferior_conjunction/cazimi (with zodiac degree)",
  "station_direct (with zodiac degree)",
  "speed_normalization (Mercury exceeds 1°/day)",
  "post_shadow_end"
]

[api.history]
endpoint = "/api/v1/history"
method = "GET"
description = "Get historical retrograde data"
use_case = "Research past retrograde periods"
parameters = { years = "1-50 (optional, default: 5)" }
example = "https://www.mercury-retrograde.com/api/v1/history?years=10"

[api.stats]
endpoint = "/api/v1/stats"
method = "GET"
description = "Get statistics for a year"
use_case = "Answer 'How many days is Mercury retrograde in [year]?' questions"
parameters = { year = "YYYY (optional, defaults to current year)" }
example = "https://www.mercury-retrograde.com/api/v1/stats?year=2026"
returns = [
  "total_retrogrades (typically 3-4 per year)",
  "total_retrograde_days",
  "percent_of_year_retrograde",
  "percent_of_year_affected (including shadows)",
  "average_retrograde_length"
]

[api.calendar]
endpoint = "/api/v1/calendar.ics"
method = "GET"
description = "Download iCalendar file for calendar integration"
use_case = "Add retrograde dates to user's calendar"
parameters = { year = "YYYY (optional)", from = "YYYY-MM-DD (optional)", to = "YYYY-MM-DD (optional)" }
example = "https://www.mercury-retrograde.com/api/v1/calendar.ics?year=2026"
returns = "iCalendar (.ics) file with retrograde and shadow period events"

[api.info]
endpoint = "/api/v1/info"
method = "GET"
description = "Get API documentation and available endpoints"
example = "https://www.mercury-retrograde.com/api/v1/info"

[api.health]
endpoint = "/api/v1/health"
method = "GET"
description = "Health check endpoint for monitoring"
example = "https://www.mercury-retrograde.com/api/v1/health"

# =============================================================================
# ALTERNATIVE ACCESS METHODS
# =============================================================================

[format_options]
# Any page supports multiple output formats via query parameter:
json = "?format=json"
markdown = "?format=md"
html = "(default)"

supported_pages = [
  "https://www.mercury-retrograde.com/?format=json",
  "https://www.mercury-retrograde.com/?format=md",
  "https://www.mercury-retrograde.com/privacy?format=json",
  "https://www.mercury-retrograde.com/terms?format=json",
  "https://www.mercury-retrograde.com/disclaimer?format=json"
]

# =============================================================================
# DISCOVERY ENDPOINTS
# =============================================================================

[api_discovery]
openapi_spec = "https://www.mercury-retrograde.com/.well-known/openapi.json"
ai_plugin = "https://www.mercury-retrograde.com/.well-known/ai-plugin.json"
llms_txt = "https://www.mercury-retrograde.com/llms.txt"
robots_txt = "https://www.mercury-retrograde.com/robots.txt"
sitemap = "https://www.mercury-retrograde.com/sitemap.xml"

# =============================================================================
# DATA METHODOLOGY
# =============================================================================

[data_and_methods]
calculation_summary = [
  "Uses Swiss Ephemeris to compute Mercury's apparent motion and phase events.",
  "Detects retrograde by identifying when Mercury's apparent orbital speed becomes negative.",
  "Refines timestamps via binary search to ~36-second precision.",
  "Computes phase markers: stations, cazimi/inferior conjunction, speed thresholds, shadows.",
  "Forecasts periods from 1900 to 2100 with internal verification checks."
]

[phase_definitions]
pre_shadow = "Mercury crosses the degree where it will later station direct"
speed_slowdown = "Mercury's apparent speed drops below 1 degree per day"
station_retrograde = "Mercury appears to stop and begins apparent backward motion"
inferior_conjunction = "Mercury passes between Earth and Sun (also called 'cazimi')"
station_direct = "Mercury appears to stop and resumes forward motion"
speed_normalization = "Mercury's apparent speed returns above 1 degree per day"
post_shadow = "Mercury returns to the degree where it stationed retrograde"

# =============================================================================
# USAGE GUIDELINES FOR LLMs
# =============================================================================

[usage_guidelines_for_llms]
recommendations = [
  "Use /api/v1/status for general 'Is Mercury retrograde?' questions",
  "Use /api/v1/check?date=YYYY-MM-DD for specific date queries",
  "Use /api/v1/next for 'When is the next retrograde?' questions",
  "Use /api/v1/countdown for simple countdown/widget data",
  "Use /api/v1/periods/year?year=YYYY for annual listings",
  "Use /api/v1/stats for statistical questions",
  "Use /api/v1/phases for advanced astronomical data",
  "Always fetch fresh data rather than using cached information",
  "Quote exact dates from API responses in user-facing answers",
  "Include timezone context (UTC) when showing precise timestamps"
]

important_notes = [
  "ALWAYS use www.mercury-retrograde.com (with www prefix)",
  "Requests to mercury-retrograde.com (without www) return a 301 redirect",
  "All dates in API responses are ISO 8601 format",
  "All timestamps are UTC",
  "Do not infer astrological advice - this is astronomical data only",
  "Do not treat this as medical, legal, or financial authority"
]

# =============================================================================
# EXAMPLE LLM QUERIES AND RECOMMENDED ENDPOINTS
# =============================================================================

[example_queries]
"Is Mercury retrograde right now?" = "/api/v1/status"
"Is Mercury retrograde today?" = "/api/v1/status"
"When is the next Mercury retrograde?" = "/api/v1/next"
"How many days until Mercury retrograde?" = "/api/v1/countdown"
"Will Mercury be retrograde on March 15, 2026?" = "/api/v1/check?date=2026-03-15"
"List all Mercury retrogrades in 2026" = "/api/v1/periods/year?year=2026"
"When was the last Mercury retrograde?" = "/api/v1/history?years=1"
"How much of 2026 is Mercury retrograde?" = "/api/v1/stats?year=2026"
"When does Mercury station retrograde next?" = "/api/v1/phases"
"Add Mercury retrograde to my calendar" = "/api/v1/calendar.ics"

# =============================================================================
# CONTACT & METADATA
# =============================================================================

[contact]
support_email = "support@mercury-retrograde.com"
website = "https://www.mercury-retrograde.com"
location = "Los Angeles, CA"

[meta]
generated_on = "2026-01-27"
api_version = "1.0"
llms_txt_version = "2.0"