https://github.com/andyfrith/weather-api

Weather API is a high-performance, type-safe RESTful service designed for the modern web. Built using the Bun JavaScript runtime and the Hono framework
https://github.com/andyfrith/weather-api

api hono openapi sentry testing types

Last synced: about 1 month ago
JSON representation

Weather API is a high-performance, type-safe RESTful service designed for the modern web. Built using the Bun JavaScript runtime and the Hono framework

• Host: GitHub
• URL: https://github.com/andyfrith/weather-api
• Owner: andyfrith
• Created: 2026-01-16T19:00:32.000Z (3 months ago)
• Default Branch: master
• Last Pushed: 2026-02-06T20:00:58.000Z (about 2 months ago)
• Last Synced: 2026-02-07T01:41:00.171Z (about 2 months ago)
• Topics: api, hono, openapi, sentry, testing, types
• Language: TypeScript
• Homepage:
• Size: 247 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# 🌤️ Weather API: Edge-First AI-Augmented Backend

[![Deployed to: Cloudflare Workers](https://img.shields.io/badge/Deployed_to-Cloudflare_Workers-F38020?style=flat-square&logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)

[![Framework: Hono](https://img.shields.io/badge/Framework-Hono-FF4500?style=flat-square&logo=hono)](https://hono.dev)

[![AI: Gemini 2.5 Flash](https://img.shields.io/badge/AI-Gemini_2.5_Flash-4285F4?style=flat-square&logo=googlegemini)](https://ai.google.dev/)

[![Documentation: OpenAPI](https://img.shields.io/badge/Docs-OpenAPI-49aa25?style=flat-square&logo=openapi-initiative)](https://swagger.io)

**Weather API** is a high-performance, type-safe service running on **Cloudflare Workers**. It combines the global scale of the edge with the lightning-fast intelligence of **Google Gemini 2.5 Flash**, providing a "Single Source of Truth" for weather data and AI-driven insights.

## ✨ Latest Features

- **🌐 Cloudflare Workers Deployment**: Optimized for the edge, leveraging Hono for sub-100ms response times globally.

- **🧠 Gemini 2.5 Flash Integration**: Uses the latest 2.5 Flash model for near-instant weather summaries, clothing recommendations, and activity suggestions with enhanced reasoning efficiency.

- **🛡️ Hono + Zod OpenAPI**: Strict contract-first development. The API is self-documenting and provides end-to-end type safety.

- **🛑 Advanced Rate Limiting**: Built-in middleware protection to manage upstream API quotas (OpenWeather & Google AI).

- **🚨 Sentry for Workers**: Specialized observability to capture and monitor edge-case errors in the serverless runtime.

---

## 🏗️ Architecture & Best Practices

### 1. Edge-Native Performance

By running **Hono** on **Cloudflare Workers**, the application utilizes a "no-cold-start" architecture, delivering data from the nearest edge node to the end user.

### 2. Intelligent Insights

The API utilizes **Gemini 2.5 Flash** to transform raw data into actionable advice.

- **Low Latency AI**: Flash 2.5 provides the speed required for real-time edge interactions.

- **Schema Validation**: Every AI-generated response is validated via Zod to ensure JSON structure integrity and prevent "hallucinations" in the UI.

### 3. Contract-First Integrity

- **Zod-to-OpenAPI**: Automated documentation ensures the UI client is always in sync with the server.

- **Type-Safe RPC**: Provides a seamless developer experience when connecting with the [Weather React Client](https://github.com/andyfrith/weather-reactjs).

---

## 🚀 Quick Start

### 1. Installation & Local Dev

```bash

git clone [https://github.com/andyfrith/weather-api.git](https://github.com/andyfrith/weather-api.git)

cd weather-api

bun install

```