ZIPFINDER
A structured, ad-free geographical lookup component built for hyperDart search.
I built ZipFinder because simple geographical searches are broken on standard search engines. If you search for "what city is zip code 10001" or "miami florida zip codes", you get directed to outdated, ad-ridden directories filled with popups and clickbait. ZipFinder solves this by bringing direct, trustworthy geographic lookups directly into hyperDart search results as an inline widget, keeping the user in the search flow and delivering structured answers in milliseconds.
✦ Overview
ZipFinder is a reusable, interactive React component designed to search, discover, and visualize geographical data through a clean, responsive, and developer-friendly interface.
Why? Geographical search is one of the most common micro-queries on the web. Bypassing spammy links to provide direct, clean answers directly aligns with hyperDart's mission to eliminate clutter and provide authoritative search results.
What makes it different?
- Zero-Dependency client-side NLU: Parses user search intent and location parameters without loading heavy external NLP libraries.
- Race Condition Prevention: Utilizes cancellation tokens (AbortController) to handle rapid re-typing and network latency smoothly.
- Developer Debugging Panel: Includes native NLU Intent and raw JSON payload viewers to inspect matched tokens on-the-fly.
✦ Features
- Smart Search — Zero-dependency client-side regex NLU that extracts US ZIP codes and City/State patterns.
- Dynamic Data — Integrates with zippopotam.us with a local backend proxy fallback for high reliability.
- NLU & JSON Inspector — Dedicated developer tabs showing matched intents and raw payload parameters.
- Try-These Chips — Clickable sample queries highlighting autocomplete values.
- Interactive UI — Autocomplete suggestion dropdown, loading animations, and clear micro-interactions.
- Responsive Design — Fully optimized for mobile screens, desktop viewports, and sidebar layouts.
- Error Handling — Custom alert states for empty queries, non-US code alerts, and network timeouts.
- Reusable Architecture — Decoupled UI presentation allows easy swap of underlying geospatial APIs.
✦ Tech Stack
| Technology | Purpose |
|---|---|
| React | Frontend UI |
| JavaScript (ES6+) | Application logic |
| CSS3 | Styling, responsiveness & micro-animations |
| Node.js | Proxy runtime |
| Cloudflare Workers / Express | Backend proxy server |
| Zippopotam.us | Live geographical REST API |
| Git & GitHub | Version control |
✦ Architecture
hyperDart Outer Search Bar
│
▼
hyperdart.config
(Triggers & regex capture query)
│
▼
ZipFinder
(searchData prop initialization)
│
▼
┌───────────────────────┐
▼ ▼
SearchBar Component nluParser.js
│ │
└──────────┬────────────┘
│
▼
api.js (fetch + AbortController)
│
┌─────────────┴─────────────┐
▼ ▼
zippopotam.us REST Backend Proxy
│ │
└─────────────┬─────────────┘
│
▼
React Render
(Tabs: Result, NLU, JSON)
│
┌────────────────┼────────────────┐
▼ ▼ ▼
LocationHero MapCard ZipList
✦ How to Run
- Clone the repo:
git clone https://github.com/hyperdart/my-sandbox-app.git cd my-sandbox-app - Install dependencies:
npm install
- Run the local dev server:
npm start
- Open your browser: Navigate to http://localhost:5173 (or the port specified by Vite).
✦ Demo
- Demo Video: JIIT Hackathon Demo Presentation (https://hyperdart.com/)
- Live Deploy: Vercel Sandbox App Deployment (https://hyperdart.com/)
✦ What I'd add with more time
- Multi-Country Live API Support: Fetch postcodes from international sources (e.g. India, UK) instead of displaying coverage alerts.
- Geocoding Search & Map Pinning: Allow users to drop a pin on a Leaflet map to reverse-geocode coordinates.
- Auto-Suggestions Database: Pre-cache common regional lookups on the proxy server for near-zero latency retrieval.