IP Geolocation 🌐 + Weather 🌦

A serverless IP geolocation service with real-time weather, air quality, forecasts, and alerts — built on Cloudflare Workers. Check it out!

Features

• 🌍 IP Geolocation - Automatic location detection using Cloudflare's edge network
• 🌤️ Weather Data - Current conditions and forecasts from National Weather Service (NWS)
• 💨 Air Quality - Real-time AQI data from World Air Quality Index and AirNow
• 🚨 Weather Alerts - Active weather warnings and advisories
• 🗺️ Interactive Map - Location visualization with MapLibre GL JS
• 📡 Radar Images - Weather radar with WebP optimization
• 🔒 Security First - CSP headers, TLS 1.2+, and modern security practices
• ⚡ Edge Performance - Global deployment via Cloudflare Workers

Tech Stack

• Runtime: Cloudflare Workers
• Language: TypeScript
• Build: Wrangler CLI
• APIs: National Weather Service, WAQI, AirNow
• Map: MapLibre GL JS with Stadia Maps

Getting Started

Prerequisites

• Node.js (v18 or later)
• pnpm package manager
• Cloudflare account
• Wrangler CLI

Installation

1. Clone the repository:

   git clone https://github.com/mdlew/ip.git
   cd ip

2. Install dependencies:

   pnpm install

3. Configure API tokens (see API Setup below)

Development

Run the development server locally:

pnpm dev

The worker will be available at http://localhost:8787

Build

Compile TypeScript to JavaScript:

pnpm build

Deployment

Deploy to Cloudflare Workers:

pnpm deploy

For automated deployment via GitHub Actions, see CI/CD Setup.

Configuration

API Setup

This project requires API keys from the following services:

1. WAQI Token (Air Quality)

   • Get your token: https://aqicn.org/data-platform/token/
   • API Documentation

2. NWS User Agent (Weather)

   • Format: (YourAppName, your@email.com)
   • API Documentation

3. AirNow API Key (Air Quality)

   • Request access: https://docs.airnowapi.org/faq
   • API Documentation

Local Development Setup

Create a .dev.vars file in the project root:

WAQI_TOKEN=your_waqi_token_here
NWS_AGENT=(YourApp, your@email.com)
AIRNOW_KEY=your_airnow_key_here

Production Setup (Cloudflare)

Set secrets using Wrangler:

wrangler secret put WAQI_TOKEN
wrangler secret put NWS_AGENT
wrangler secret put AIRNOW_KEY

CI/CD Setup

For automated deployment via GitHub Actions, add these secrets to your repository (Settings → Secrets and variables → Actions):

• CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID
• CLOUDFLARE_API_TOKEN - API token with Workers edit permissions
• WAQI_TOKEN - Air quality API token
• NWS_AGENT - Weather.gov user agent string
• AIRNOW_KEY - AirNow API key

Project Structure

ip/
├── src/
│   ├── index.ts    # Main entry point and request router
│   ├── ssr.ts      # Server-side rendering logic
│   └── utils.ts    # Utility functions and helpers
├── public/         # Static assets (fonts, robots.txt)
├── wrangler.toml   # Cloudflare Workers configuration
├── package.json    # Dependencies and scripts
└── tsconfig.json   # TypeScript configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is open source and available under the MIT License.

Credits

Built by Matthew Lew

Adapted from:

• Cloudflare Workers Examples
• NikSec IP Check Tool

Acknowledgments

• Weather data provided by National Weather Service
• Air quality data from WAQI and AirNow
• Maps powered by MapLibre GL JS and Stadia Maps