{
  "title": "Date Normalizer API Documentation",
  "version": "2.1",
  "base_url": "date-normalizer-v2.tomjstone.workers.dev",
  "endpoints": {
    "normalize": {
      "method": "POST",
      "path": "/v2/normalize",
      "description": "Parse and normalize a single date with timezone conversion",
      "request_body": {
        "date": {
          "type": "string",
          "required": true,
          "description": "Date string in various formats including natural language",
          "examples": [
            "7/4/25 5pm PST",
            "2025-07-04T17:00:00-07:00",
            "July 4, 2025 5:00 PM",
            "tomorrow at 3pm",
            "next Friday 2pm EST",
            "in 3 hours",
            "last Monday"
          ]
        },
        "assume_tz": {
          "type": "string",
          "required": false,
          "default": "UTC",
          "description": "IANA timezone to assume when input has no timezone",
          "examples": [
            "America/Los_Angeles",
            "Europe/London",
            "Asia/Tokyo"
          ]
        },
        "output_tz": {
          "type": "string",
          "required": false,
          "default": "UTC",
          "description": "IANA timezone for normalized output",
          "examples": [
            "UTC",
            "America/New_York",
            "Europe/Paris"
          ]
        },
        "reference_time": {
          "type": "string",
          "required": false,
          "description": "ISO timestamp to use as reference for relative dates (defaults to now)",
          "example": "2025-08-27T12:00:00Z"
        }
      }
    },
    "batch": {
      "method": "POST",
      "path": "/v2/batch",
      "description": "Process multiple dates in a single request (max 50)",
      "request_body": {
        "dates": {
          "type": "array",
          "required": true,
          "description": "Array of date objects to process",
          "items": {
            "date": "string (required)",
            "assume_tz": "string (optional)",
            "output_tz": "string (optional)"
          }
        },
        "reference_time": {
          "type": "string",
          "required": false,
          "description": "Reference time for all relative dates"
        }
      }
    },
    "validate": {
      "method": "POST",
      "path": "/v2/validate",
      "description": "Check if a date string can be parsed",
      "request_body": {
        "date": {
          "type": "string",
          "required": true,
          "description": "Date string to validate"
        },
        "reference_time": {
          "type": "string",
          "required": false,
          "description": "Reference time for relative date validation"
        }
      }
    }
  },
  "supported_formats": {
    "absolute_dates": {
      "us_style": [
        "M/D/YY",
        "M/D/YYYY",
        "MM/DD/YY H:mm AM/PM TZ"
      ],
      "iso_style": [
        "YYYY-MM-DD",
        "YYYY-MM-DDTHH:mm:ss.sssZ",
        "YYYY-MM-DD HH:mm TZ"
      ],
      "natural": [
        "Month DD, YYYY",
        "DD Month YYYY HH:mm",
        "Month DD at H:mm AM/PM"
      ]
    },
    "relative_dates": {
      "simple": [
        "now",
        "today",
        "tomorrow",
        "yesterday"
      ],
      "relative": [
        "in X minutes/hours/days/weeks/months",
        "X days ago"
      ],
      "named_days": [
        "next/last Monday/Tuesday/etc",
        "this Friday"
      ],
      "time_expressions": [
        "at 3pm",
        "at 15:30",
        "in the morning/afternoon/evening"
      ]
    },
    "timezones": {
      "abbreviations": [
        "PST",
        "EST",
        "GMT",
        "UTC",
        "CET",
        "JST",
        "IST"
      ],
      "offsets": [
        "+05:30",
        "-07:00",
        "+0000",
        "Z"
      ],
      "iana": [
        "America/Los_Angeles",
        "Europe/London",
        "Asia/Tokyo",
        "America/New_York"
      ]
    }
  },
  "confidence_levels": {
    "0.9-1.0": "Very high confidence - explicit timezone or well-defined format",
    "0.7-0.89": "High confidence - clear format with minor assumptions",
    "0.5-0.69": "Medium confidence - some ambiguity resolved with assumptions",
    "0.3-0.49": "Low confidence - significant assumptions made",
    "0.0-0.29": "Very low confidence - fallback parsing used"
  }
}