mapquest-agent-skills 1.0.0

package/skills/mapquest-geocoding-patterns/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: mapquest-geocoding-patterns
+description: Address-to-coordinate and coordinate-to-address conversion using the MapQuest Geocoding API. Covers forward geocoding, reverse geocoding, batch geocoding, quality codes, and response parsing.
+---
+
+# MapQuest Geocoding Patterns
+
+## Overview
+
+The MapQuest Geocoding API converts between addresses and geographic coordinates. Base URL: `https://www.mapquestapi.com/geocoding/v1`
+
+Always append `?key=YOUR_API_KEY` to every request. Never hardcode the key — use environment variables (`MAPQUEST_API_KEY` or `VITE_MAPQUEST_API_KEY` for Vite projects).
+
+---
+
+## Geocoding Modes
+
+### 1. Forward Geocoding (Address → Lat/Lng)
+
+**Endpoint:** `GET /geocoding/v1/address`
+
+```js
+const response = await fetch(
+  `https://www.mapquestapi.com/geocoding/v1/address?key=${apiKey}&location=${encodeURIComponent(address)}`
+);
+const data = await response.json();
+const { lat, lng } = data.results[0].locations[0].latLng;
+```
+
+**Always check `geocodeQuality` before trusting the result:**
+
+| Quality Code | Meaning | Trust Level |
+|---|---|---|
+| `POINT` | Rooftop/parcel level | ✅ High |
+| `ADDRESS` | Interpolated street address | ✅ High |
+| `INTERSECTION` | Street intersection | ✅ Medium |
+| `STREET` | Street-level match | ⚠️ Medium |
+| `ZIP` | ZIP code centroid | ⚠️ Low |
+| `CITY` | City centroid | ❌ Low |
+| `COUNTY` | County centroid | ❌ Low |
+| `STATE` | State centroid | ❌ Low |
+| `COUNTRY` | Country centroid | ❌ Very Low |
+
+```js
+// Always validate quality before using coords
+const location = data.results[0].locations[0];
+const ACCEPTABLE_QUALITY = ['POINT', 'ADDRESS', 'INTERSECTION', 'STREET'];
+
+if (!ACCEPTABLE_QUALITY.includes(location.geocodeQuality)) {
+  // Prompt user to refine their address
+  showAddressRefinementPrompt();
+  return;
+}
+```
+
+### 2. Reverse Geocoding (Lat/Lng → Address)
+
+**Endpoint:** `GET /geocoding/v1/reverse`
+
+```js
+const response = await fetch(
+  `https://www.mapquestapi.com/geocoding/v1/reverse?key=${apiKey}&location=${lat},${lng}`
+);
+const data = await response.json();
+const address = data.results[0].locations[0];
+// address.street, address.adminArea5 (city), address.adminArea3 (state), address.postalCode
+```
+
+### 3. Batch Geocoding (Multiple Addresses)
+
+**Endpoint:** `POST /geocoding/v1/batch`
+
+Use batch geocoding when converting 2–100 addresses. More efficient than individual requests.
+
+```js
+const response = await fetch(
+  `https://www.mapquestapi.com/geocoding/v1/batch?key=${apiKey}`,
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      locations: [
+        '1600 Pennsylvania Ave NW, Washington, DC',
+        'Times Square, New York, NY',
+        'Golden Gate Bridge, San Francisco, CA'
+      ],
+      options: { thumbMaps: false } // Set false unless you need thumbnail map images
+    })
+  }
+);
+const data = await response.json();
+// data.results is an array matching input order
+```
+
+**Batch limits:** Max 100 locations per request. For larger sets, chunk the array.
+
+```js
+function chunk(arr, size) {
+  return Array.from({ length: Math.ceil(arr.length / size) }, (_, i) =>
+    arr.slice(i * size, i * size + size)
+  );
+}
+
+async function batchGeocode(addresses) {
+  const chunks = chunk(addresses, 100);
+  const results = [];
+  for (const batch of chunks) {
+    const res = await geocodeBatch(batch);
+    results.push(...res.results);
+    // Add delay between batches to avoid rate limits
+    await new Promise(r => setTimeout(r, 200));
+  }
+  return results;
+}
+```
+
+---
+
+## Request Options
+
+```js
+{
+  options: {
+    thumbMaps: false,        // Skip thumbnail images (saves bandwidth, faster response)
+    maxResults: 1,           // Limit ambiguous address matches (default: 1)
+    ignoreLatLngInput: true, // Always geocode even if lat/lng supplied in location
+    boundingBox: {           // Bias results to a bounding box
+      ul: { lat: 40.9, lng: -74.3 },
+      lr: { lat: 40.4, lng: -73.6 }
+    }
+  }
+}
+```
+
+---
+
+## Response Parsing
+
+```js
+// Safe response parser with fallbacks
+function parseGeocodingResult(data) {
+  if (!data?.results?.[0]?.locations?.[0]) {
+    return null;
+  }
+  const loc = data.results[0].locations[0];
+  return {
+    lat: loc.latLng.lat,
+    lng: loc.latLng.lng,
+    quality: loc.geocodeQuality,
+    qualityCode: loc.geocodeQualityCode,
+    street: loc.street,
+    city: loc.adminArea5,
+    county: loc.adminArea4,
+    state: loc.adminArea3,
+    country: loc.adminArea1,
+    zip: loc.postalCode,
+    formatted: [loc.street, loc.adminArea5, loc.adminArea3, loc.postalCode]
+      .filter(Boolean)
+      .join(', ')
+  };
+}
+```
+
+---
+
+## Common Mistakes to Avoid
+
+❌ **Don't** use coordinates from a CITY or ZIP quality result for precise operations like routing or distance calculations — the coords are just the centroid.
+
+❌ **Don't** geocode on every keystroke. Debounce or wait for form submission.
+
+❌ **Don't** ignore the `info.statuscode` field. `0` = success. Any other value is an error.
+
+```js
+if (data.info.statuscode !== 0) {
+  console.error('Geocoding error:', data.info.messages);
+}
+```
+
+❌ **Don't** expose your API key in client-side code for production apps. Use a backend proxy.
+
+✅ **Do** set `thumbMaps: false` unless you actually need the thumbnail — it speeds up responses.
+
+✅ **Do** cache geocoding results for addresses you'll look up repeatedly.
+
+---
+
+## Structured Address Input (More Accurate)
+
+Instead of a raw string, pass a structured location object for higher accuracy:
+
+```js
+const response = await fetch(
+  `https://www.mapquestapi.com/geocoding/v1/address?key=${apiKey}`,
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      location: {
+        street: '1090 N Charlotte St',
+        city: 'Lancaster',
+        state: 'PA',
+        postalCode: '17603',
+        country: 'US'
+      },
+      options: { thumbMaps: false }
+    })
+  }
+);
+```
+
+---
+
+## Error Handling Template
+
+```js
+async function geocodeAddress(address, apiKey) {
+  try {
+    const url = `https://www.mapquestapi.com/geocoding/v1/address?key=${apiKey}&location=${encodeURIComponent(address)}&thumbMaps=false`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error: ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    if (data.info.statuscode !== 0) {
+      throw new Error(`MapQuest error: ${data.info.messages.join(', ')}`);
+    }
+
+    const result = parseGeocodingResult(data);
+    if (!result) {
+      throw new Error('No results found for this address');
+    }
+
+    return result;
+  } catch (error) {
+    console.error('Geocoding failed:', error);
+    throw error;
+  }
+}
+```

package/skills/mapquest-key-security/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: mapquest-key-security
+description: Best practices for securing MapQuest API keys. Covers environment variables, referrer restrictions, server-side proxying, key rotation, and incident response when a key is exposed.
+---
+
+# MapQuest API Key Security
+
+## Overview
+
+Your MapQuest API key is a secret credential. Exposing it allows others to use your quota, incur charges on your account, and potentially abuse MapQuest services. Always treat API keys like passwords.
+
+---
+
+## The Golden Rules
+
+1. **Never hardcode an API key in source code**
+2. **Never commit a key to version control**
+3. **Use referrer restrictions in the MapQuest developer portal**
+4. **For server-rendered or backend apps: proxy all MapQuest requests through your server**
+5. **Rotate keys if you suspect exposure**
+
+---
+
+## Environment Variable Storage
+
+### Frontend (Vite / React / Vue)
+
+```bash
+# .env.local (never commit this file)
+VITE_MAPQUEST_API_KEY=your_key_here
+```
+
+```js
+// Access in code:
+const apiKey = import.meta.env.VITE_MAPQUEST_API_KEY;
+```
+
+```
+# .gitignore — ensure .env files are excluded
+.env
+.env.local
+.env*.local
+```
+
+### Backend (Node.js)
+
+```bash
+# .env
+MAPQUEST_API_KEY=your_key_here
+```
+
+```js
+require('dotenv').config();
+const apiKey = process.env.MAPQUEST_API_KEY;
+```
+
+### Never do this:
+
+```js
+// ❌ WRONG — key is visible in source code and bundle
+const apiKey = 'Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9';
+
+// ❌ WRONG — key in git history forever
+// git commit -m "added api key"
+```
+
+---
+
+## Referrer Restrictions (Developer Portal)
+
+In the [MapQuest Developer Portal](https://developer.mapquest.com), set **Allowed Referrers** for each key:
+
+- `https://yourdomain.com/*` — production
+- `https://staging.yourdomain.com/*` — staging
+- `http://localhost:*` — local development
+
+This limits the key to only work when requests originate from your domains. Client-side keys with referrer restrictions are significantly safer than unrestricted keys.
+
+**Limitation:** Referrer headers can be spoofed by determined bad actors. For truly sensitive apps, use server-side proxying instead.
+
+---
+
+## Server-Side Proxy (Recommended for Production)
+
+Never send MapQuest API requests directly from client-side code in production. Instead, proxy through your backend:
+
+```js
+// Express.js proxy route
+const express = require('express');
+const router = express.Router();
+
+router.get('/geocode', async (req, res) => {
+  const { address } = req.query;
+
+  // Validate input
+  if (!address || address.length > 500) {
+    return res.status(400).json({ error: 'Invalid address' });
+  }
+
+  // Optional: rate limit per user/IP here
+
+  try {
+    const response = await fetch(
+      `https://www.mapquestapi.com/geocoding/v1/address?key=${process.env.MAPQUEST_API_KEY}&location=${encodeURIComponent(address)}&thumbMaps=false`
+    );
+    const data = await response.json();
+    res.json(data);
+  } catch (err) {
+    res.status(500).json({ error: 'Geocoding service unavailable' });
+  }
+});
+```
+
+```js
+// Client-side — call your proxy, not MapQuest directly
+const response = await fetch(`/api/geocode?address=${encodeURIComponent(address)}`);
+```
+
+**Benefits of proxying:**
+- API key never exposed to browser
+- You can rate-limit per user
+- You can cache responses
+- You can log and monitor usage
+
+---
+
+## Key Rotation Strategy
+
+Create multiple keys in the MapQuest Developer Portal:
+
+| Key Name | Purpose | Restrictions |
+|---|---|---|
+| `production-web` | Live site | Referrer: `https://yourdomain.com/*` |
+| `staging-web` | Staging environment | Referrer: `https://staging.yourdomain.com/*` |
+| `development` | Local dev | Referrer: `http://localhost:*` |
+| `server-side` | Backend proxy | No referrer (IP-restricted if possible) |
+
+Rotate keys every 90 days or immediately after any potential exposure.
+
+---
+
+## Incident Response: Exposed Key
+
+If you suspect a key was exposed (e.g., committed to a public repo):
+
+1. **Immediately regenerate/revoke the key** in the MapQuest Developer Portal
+2. **Deploy a new key** from your secure environment variable store
+3. **Purge git history** if committed (use `git filter-branch` or BFG Repo Cleaner)
+4. **Check MapQuest usage logs** for unusual activity
+5. **Notify your team** and update deployment pipelines
+
+```bash
+# If key was committed — remove from git history
+# Install BFG: https://rtyley.github.io/bfg-repo-cleaner/
+bfg --replace-text secrets.txt my-repo.git
+git push --force
+```
+
+---
+
+## Checklist for Every Project
+
+- [ ] API key stored in `.env` / environment variable, never in source code
+- [ ] `.env` files added to `.gitignore`
+- [ ] Referrer restrictions configured in MapQuest Developer Portal
+- [ ] Separate keys for production, staging, and development
+- [ ] Server-side proxy implemented for production (recommended)
+- [ ] Key rotation schedule documented (every 90 days)
+- [ ] Team members aware not to log or share keys in chat/tickets
+
+---
+
+## What Not to Do
+
+❌ Don't log API keys in console.log or server logs
+
+❌ Don't share API keys in Slack, email, or issue trackers
+
+❌ Don't use the same key for development and production
+
+❌ Don't store keys in local storage or cookies (accessible to JS/XSS)
+
+❌ Don't put keys in URLs (they appear in server logs and browser history)

package/skills/mapquest-search-ahead/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: mapquest-search-ahead
+description: Typeahead and autocomplete using the MapQuest Search Ahead API. Covers debouncing, result categories, geographic bias, collection types, and chaining with the Geocoding API.
+---
+
+# MapQuest Search Ahead Patterns
+
+## Overview
+
+The Search Ahead API powers autocomplete/typeahead address and POI search. Base URL: `https://www.mapquestapi.com/search/v3/prediction`
+
+Use this for live search inputs, not for batch geocoding or one-shot address resolution. For a single definitive address lookup, use the Geocoding API.
+
+---
+
+## Basic Search Ahead Request
+
+```js
+const response = await fetch(
+  `https://www.mapquestapi.com/search/v3/prediction?key=${apiKey}&q=${encodeURIComponent(query)}&collection=address,adminArea,poi`
+);
+const data = await response.json();
+// data.results is an array of prediction objects
+```
+
+---
+
+## Collection Types
+
+The `collection` parameter controls what types of results are returned. Always specify what you need — don't request everything.
+
+| Collection | Description | Use When |
+|---|---|---|
+| `address` | Street addresses | Address entry forms |
+| `adminArea` | Cities, states, countries | Location pickers |
+| `airport` | Airport names + IATA codes | Travel apps |
+| `category` | Category labels (e.g., "restaurants") | Search-by-type UIs |
+| `franchise` | Chain business names (e.g., "Starbucks") | Store locators |
+| `poi` | Individual points of interest | General search |
+
+```js
+// Address-only (fastest, most relevant for delivery/shipping forms)
+collection=address
+
+// Address + city for flexible location search
+collection=address,adminArea
+
+// Full search (POI + address + city)
+collection=poi,address,adminArea
+```
+
+---
+
+## Geographic Bias
+
+Bias results toward a location to get more relevant suggestions:
+
+```js
+const params = new URLSearchParams({
+  key: apiKey,
+  q: query,
+  collection: 'address,poi',
+  location: `${userLng},${userLat}`,  // NOTE: lng,lat order (not lat,lng!)
+  limit: 5,
+});
+```
+
+**Critical:** The `location` parameter uses **longitude, latitude** order (opposite of most MapQuest parameters).
+
+---
+
+## Debouncing — Required
+
+Always debounce Search Ahead requests. Fire no more than once per 300–500ms. Never call the API on every keystroke.
+
+```js
+// Vanilla JS debounce
+function debounce(fn, delay) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), delay);
+  };
+}
+
+const searchInput = document.getElementById('search');
+const resultsContainer = document.getElementById('results');
+
+const handleSearch = debounce(async (query) => {
+  if (query.length < 2) {
+    resultsContainer.innerHTML = '';
+    return;
+  }
+
+  const data = await searchAhead(query);
+  renderResults(data.results);
+}, 300);
+
+searchInput.addEventListener('input', e => handleSearch(e.target.value));
+```
+
+```js
+// React hook with debounce
+import { useState, useEffect } from 'react';
+
+function useSearchAhead(apiKey, debounceMs = 300) {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (query.length < 2) {
+      setResults([]);
+      return;
+    }
+
+    const timer = setTimeout(async () => {
+      setLoading(true);
+      try {
+        const data = await fetchPredictions(query, apiKey);
+        setResults(data.results || []);
+      } catch (e) {
+        console.error(e);
+      } finally {
+        setLoading(false);
+      }
+    }, debounceMs);
+
+    return () => clearTimeout(timer);
+  }, [query, apiKey, debounceMs]);
+
+  return { query, setQuery, results, loading };
+}
+```
+
+---
+
+## Parsing Results
+
+```js
+function parsePrediction(result) {
+  return {
+    id: result.id,
+    displayString: result.displayString,   // Human-readable label
+    place: result.place,                   // Detailed place info
+    collection: result.collection,         // 'address', 'poi', etc.
+    // For addresses:
+    street: result.place?.properties?.street,
+    city: result.place?.properties?.city,
+    state: result.place?.properties?.stateCode,
+    zip: result.place?.properties?.postalCode,
+    country: result.place?.properties?.countryCode,
+    // Coordinates (if available in result):
+    lat: result.place?.geometry?.coordinates?.[1],
+    lng: result.place?.geometry?.coordinates?.[0],
+  };
+}
+```
+
+---
+
+## Chaining Search Ahead → Geocoding
+
+Search Ahead results often don't include precise lat/lng coordinates. Chain with the Geocoding API to resolve:
+
+```js
+async function selectPrediction(prediction, apiKey) {
+  // Some predictions include coordinates directly
+  if (prediction.place?.geometry?.coordinates) {
+    const [lng, lat] = prediction.place.geometry.coordinates;
+    return { lat, lng, label: prediction.displayString };
+  }
+
+  // Otherwise, geocode the display string
+  const geoResult = await geocodeAddress(prediction.displayString, apiKey);
+  return {
+    lat: geoResult.lat,
+    lng: geoResult.lng,
+    label: prediction.displayString,
+  };
+}
+```
+
+---
+
+## Full Autocomplete Component (Vanilla JS)
+
+```js
+class MapQuestAutocomplete {
+  constructor(inputEl, apiKey, onSelect) {
+    this.input = inputEl;
+    this.apiKey = apiKey;
+    this.onSelect = onSelect;
+    this.dropdown = this.createDropdown();
+    this.debounceTimer = null;
+
+    this.input.addEventListener('input', () => this.handleInput());
+    this.input.addEventListener('blur', () => setTimeout(() => this.hide(), 200));
+    document.addEventListener('click', e => {
+      if (!this.input.contains(e.target)) this.hide();
+    });
+  }
+
+  createDropdown() {
+    const el = document.createElement('ul');
+    el.style.cssText = 'position:absolute;background:#fff;border:1px solid #ccc;list-style:none;margin:0;padding:0;width:100%;z-index:1000;display:none';
+    this.input.parentElement.style.position = 'relative';
+    this.input.parentElement.appendChild(el);
+    return el;
+  }
+
+  handleInput() {
+    clearTimeout(this.debounceTimer);
+    const q = this.input.value.trim();
+    if (q.length < 2) { this.hide(); return; }
+    this.debounceTimer = setTimeout(() => this.search(q), 300);
+  }
+
+  async search(q) {
+    const url = `https://www.mapquestapi.com/search/v3/prediction?key=${this.apiKey}&q=${encodeURIComponent(q)}&collection=address,adminArea,poi&limit=5`;
+    const res = await fetch(url);
+    const data = await res.json();
+    this.show(data.results || []);
+  }
+
+  show(results) {
+    this.dropdown.innerHTML = '';
+    results.forEach(r => {
+      const li = document.createElement('li');
+      li.textContent = r.displayString;
+      li.style.cssText = 'padding:8px 12px;cursor:pointer';
+      li.addEventListener('mouseover', () => li.style.background = '#f0f0f0');
+      li.addEventListener('mouseout', () => li.style.background = '');
+      li.addEventListener('click', () => {
+        this.input.value = r.displayString;
+        this.hide();
+        this.onSelect(r);
+      });
+      this.dropdown.appendChild(li);
+    });
+    this.dropdown.style.display = results.length ? 'block' : 'none';
+  }
+
+  hide() { this.dropdown.style.display = 'none'; }
+}
+
+// Usage:
+const autocomplete = new MapQuestAutocomplete(
+  document.getElementById('address-input'),
+  'YOUR_API_KEY',
+  async (prediction) => {
+    const location = await selectPrediction(prediction, 'YOUR_API_KEY');
+    map.setCenter([location.lat, location.lng]);
+  }
+);
+```
+
+---
+
+## Common Mistakes to Avoid
+
+❌ **Don't** fire Search Ahead on every keypress — always debounce.
+
+❌ **Don't** set `limit` higher than needed (max 10). Larger result sets are slower and rarely improve UX.
+
+❌ **Don't** confuse `location` parameter order. Search Ahead uses **lng,lat**. Geocoding API uses **lat,lng**. Always double-check.
+
+❌ **Don't** assume Search Ahead results include coordinates. They may not — always check before using and fall back to geocoding.
+
+✅ **Do** set a minimum character threshold (2–3 chars) before calling the API.
+
+✅ **Do** cancel in-flight requests when a newer query supersedes them (use AbortController).
+
+```js
+let controller;
+
+async function fetchPredictions(q, apiKey) {
+  if (controller) controller.abort();
+  controller = new AbortController();
+
+  const res = await fetch(url, { signal: controller.signal });
+  return res.json();
+}
+```
+
+✅ **Do** handle network errors gracefully — the dropdown should fail silently, not crash the page.