{"id":50705432,"url":"https://github.com/sudo-py-dev/hebcal-api","last_synced_at":"2026-06-09T11:01:50.263Z","repository":{"id":316665790,"uuid":"1064362469","full_name":"sudo-py-dev/hebcal-api","owner":"sudo-py-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-10T15:00:51.000Z","size":143,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T17:05:46.929Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sudo-py-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T23:35:41.000Z","updated_at":"2026-04-10T15:00:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"06486ebe-b374-4960-9109-5532dc8f6a46","html_url":"https://github.com/sudo-py-dev/hebcal-api","commit_stats":null,"previous_names":["sudo-py-dev/hebcal-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sudo-py-dev/hebcal-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Fhebcal-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Fhebcal-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Fhebcal-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Fhebcal-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sudo-py-dev","download_url":"https://codeload.github.com/sudo-py-dev/hebcal-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudo-py-dev%2Fhebcal-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34103357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T11:01:50.143Z","updated_at":"2026-06-09T11:01:50.252Z","avatar_url":"https://github.com/sudo-py-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hebcal API Client\n\n[![PyPI version](https://badge.fury.io/py/hebcal-api.svg)](https://badge.fury.io/py/hebcal-api)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/sudo-py-dev/hebcal-api/blob/main/LICENSE)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\nA comprehensive, production-grade Python client for the [Hebcal Jewish Calendar API](https://www.hebcal.com/home/195/jewish-calendar-rest-api). Modernized with **Pydantic v2**, **httpx**, and **strict type safety**.\n\n## Features\n\n- 🗓️ **Functional API** - Clean, functional interface for all Hebcal endpoints.\n- ✅ **Pydantic Validation** - Type-safe request models with automatic parameter validation.\n- 🇮🇱 **Clean Hebrew Output** - Specialized formatters that prioritize clean, nikud-free Hebrew text.\n- 🕯️ **Advanced Shabbat \u0026 Zmanim** - Precise halachic times for any location worldwide.\n- 🌾 **Omer Support** - Full support for fetching and formatting the daily Omer count.\n- ⚡ **Async Native** - Built on `httpx` for high-performance asynchronous operations.\n- 📍 **Flattened Location Support** - Direct use of Geonames, coordinates, or city names.\n\n## Installation\n\n```bash\npip install hebcal-api\n```\n\nOr with `uv`:\n\n```bash\nuv add hebcal-api\n```\n\n## Quick Start\n\n### Basic Calendar Usage\nGet Jewish holidays and events for any location.\n\n```python\nfrom hebcal_api import CalendarRequest, fetch_calendar\nfrom hebcal_api.utils.calendar_formatter import format_calendar_events\n\n# Create a request for Jerusalem\nrequest = CalendarRequest(\n    location=\"Jerusalem\",\n    geonameid=281184,\n    maj=True,    # Major holidays\n    min=True     # Minor holidays\n)\n\n# Fetch data synchronously\nresponse = fetch_calendar(request)\n\n# Format for display (Always clean Hebrew by default)\nprint(format_calendar_events(response))\n```\n\n### Shabbat Times\nFetch candle lighting and Havdalah times.\n\n```python\nfrom hebcal_api import ShabbatRequest, fetch_shabbat\n\nrequest = ShabbatRequest(\n    geonameid=5128581,  # New York City\n    c=True,             # Candle lighting\n    s=True              # Shabbat info\n)\n\nresponse = fetch_shabbat(request)\n\nfor event in response.items:\n    print(f\"{event.title}: {event.date}\")\n```\n\n### Omer Count Today\nEasily track the daily Omer count.\n\n```python\nfrom hebcal_api import CalendarRequest, fetch_calendar\n\nrequest = CalendarRequest(o=True)  # Enable Omer count\nresponse = fetch_calendar(request)\n\n# Find the Omer event\nomer_event = next((i for i in response.items if i.type == \"omer\"), None)\nif omer_event:\n    print(f\"Today is: {omer_event.title}\")\n```\n\n### Async Usage\nFull async support for integration into modern web frameworks.\n\n```python\nimport asyncio\nfrom hebcal_api import CalendarRequest, fetch_calendar_async\n\nasync def main():\n    request = CalendarRequest(geonameid=281184)\n    response = await fetch_calendar_async(request)\n    \n    for event in response.items:\n        print(f\"{event.title} - {event.hebrew}\")\n\nasyncio.run(main())\n```\n\n## API Reference\n\n### Functional Interface\nThe library provides high-level `fetch_*` functions for both sync and async execution:\n\n| Endpoint | Sync Function | Async Function |\n| :--- | :--- | :--- |\n| `/hebcal` | `fetch_calendar` | `fetch_calendar_async` |\n| `/shabbat` | `fetch_shabbat` | `fetch_shabbat_async` |\n| `/zmanim` | `fetch_zmanim` | `fetch_zmanim_async` |\n| `/converter` | `fetch_converter` | `fetch_converter_async` |\n| `/yahrzeit` | `fetch_yahrzeit` | `fetch_yahrzeit_async` |\n| `/leyning` | `fetch_leyning` | `fetch_leyning_async` |\n\n### Unified Client\nFor custom network configuration, use the `HebcalClient`:\n\n```python\nfrom hebcal_api import HebcalClient\n\n# Configure custom timeout or headers\nresponse = HebcalClient.execute(\n    endpoint=Endpoint.CALENDAR,\n    request=request,\n    response_model=CalendarResponse,\n    timeout=30\n)\n```\n\n## Error Handling\n\nThe library uses a hierarchy of specific exceptions:\n\n- `HebcalError`: Base exception for all library errors.\n- `HebcalNetworkError`: Raised for HTTP connection or status code failures.\n- `HebcalValidationError`: Raised when request parameters are invalid (e.g., missing location).\n- `HebcalParseError`: Raised when the API response cannot be parsed into the expected models.\n\n## Formatting Utilities\nLocated in `hebcal_api.utils.calendar_formatter`, these helper functions turn raw data into professional messages.\n\n- `format_calendar_events(response)`: Returns a beautiful, multi-line string of events.\n- `remove_hebrew_nikud(text)`: Manually strip diacritics from any Hebrew string.\n\n## Development\n\nSet up the project using `uv`:\n\n```bash\ngit clone https://github.com/sudo-py-dev/hebcal-api.git\ncd hebcal-api\nuv sync\n```\n\n### Code Quality\nWe enforce strict linting and type checking:\n\n```bash\nuv run ruff check      # Linting\nuv run ruff format     # Formatting\nuv run pyright src/    # Type safety\nuv run pytest          # Testing\n```\n\n## License\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Support\n- 📧 Email: sudopydev@gmail.com\n- 🐛 [GitHub Issues](https://github.com/sudo-py-dev/hebcal-api/issues)\n- 📖 [Official API Documentation](https://www.hebcal.com/home/195/jewish-calendar-rest-api)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudo-py-dev%2Fhebcal-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsudo-py-dev%2Fhebcal-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudo-py-dev%2Fhebcal-api/lists"}