TabQuest Weather API

A lightweight, production-ready weather proxy API built on Val Town. Powers the TabQuest browser extension.

Built on top of OpenWeatherMap with Redis-backed rate limiting and caching via Upstash.

Features

Current weather by city name
IP-based rate limiting (10 requests/min per IP)
30-minute Redis cache per city — reduces OpenWeather API calls
Clean error responses — no internal details leaked to clients
CORS enabled — works from browser extensions and web clients

API Usage

Endpoint

GET https://tabquest.val.run/weather?city=London

Parameters

Parameter	Type	Required	Description
`city`	string	Yes	City name to query

Example Request

curl "https://tabquest.val.run/weather?city=Chennai"

Example Response

{
  "coord": { "lon": 80.2785, "lat": 13.0878 },
  "weather": [{ "id": 801, "main": "Clouds", "description": "few clouds" }],
  "main": {
    "temp": 305.15,
    "feels_like": 309.22,
    "humidity": 70
  },
  "wind": { "speed": 5.14 },
  "name": "Chennai"
}

Note: Temperatures are returned in Kelvin by default (OpenWeatherMap standard). Unit conversion should be handled on the client side.

Response Headers

Header	Value	Meaning
`X-Cache`	`HIT` or `MISS`	Whether response was cached

Error Responses

Status	Message	Reason
`400`	`Missing 'city' parameter`	No city provided
`400`	`Invalid city name`	City contains invalid characters
`404`	`City not found`	OpenWeather couldn't find city
`404`	`Route not found`	Invalid endpoint path
`429`	`Rate limit exceeded. Try again in a minute`	Too many requests from your IP
`500`	`Service misconfigured`	Missing env vars on server
`502`	`Weather service error. Try again later`	OpenWeather upstream error

Self-Hosting

This API is designed to be self-hosted on Val Town. You'll need your own API keys.

1. Fork the Val

Go to the Val Town project and click Remix.

2. Set Environment Variables

Go to val.town/settings/environment-variables and add:

Variable	Description
`OPENWEATHER_API_KEY`	Your OpenWeatherMap API key
`UPSTASH_URL`	REST URL from your Upstash Redis database
`UPSTASH_TOKEN`	REST token from your Upstash Redis database

See docs/env-variables.md for detailed setup instructions.

3. Deploy

Val Town deploys automatically on save. Your endpoint will be live at:

https://<your-username>.val.run/weather

Project Structure

tabquest-weather-api/
├── src/
│   ├── routes/
│   │   └── weather.ts  ← weather route handler
│   ├── config.ts       ← constants (rate limit, cache TTL, validation regex)
│   ├── env.ts          ← env var validation + types
│   ├── http.ts         ← CORS headers + JSON response helpers
│   ├── redis.ts        ← Redis client, rate limiting, caching
│   └── weather.ts      ← OpenWeather fetch + error mapping
├── main.ts             ← HTTP entry point + routing
├── docs/
│   ├── setup.md
│   ├── env-variables.md
│   └── rate-limiting.md
└── README.md

Configuration

All tuneable values live in src/config.ts:

export const RATE_LIMIT = 10;          // requests per window per IP
export const RATE_WINDOW_SEC = 60;     // rate limit window in seconds
export const CACHE_TTL_SEC = 60 * 30;  // cache TTL (30 minutes)

Contributing

Fork the repo
Create a branch: git checkout -b feat/your-feature
Make your changes
Open a pull request

Please open an issue before working on large changes.

Part of TabQuest

This API powers TabQuest — an open source browser extension.

⭐ If you find this useful, consider starring the main repo.

tabquest/tabquest — The open source browser extension this API was built for.