MapOps - Conversational City Analyst

A map-based AI agent that understands natural language and acts on maps to help people explore a city, decide where to go, and discover places tailored to their preferences.

Built in 18 hours during the YC Agent Jam '25 Hackathon (November 1-2, 2025, San Francisco, CA)

Demo

Click to watch the full demo on YouTube

Features

• Interactive Google Maps view
• Natural language query processing
• Place search and filtering
• Walking distance calculations
• Real-time location detection

Setup Instructions

1. Get Google Maps API Key

1. Go to Google Cloud Console

2. Create a new project or select an existing one

3. Enable the following APIs:

   • Maps JavaScript API
   • Places API (New)
   • Routes API
   • Distance Matrix API
   • Geocoding API

4. Create an API key:

   • Navigate to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "API Key"
   • Restrict the key to the APIs you're using (recommended)

5. Enable the following APIs:

   • Maps JavaScript API
   • Places API (New)
   • Places Aggregate API
   • Routes API
   • Distance Matrix API (or use Routes API)
   • Geocoding API
   • Roads API
   • Route Optimization API

2. Configure API Key

1. Copy the example config file:

   cp config.example.js config.js

2. Open config.js and replace YOUR_API_KEY_HERE with your actual API key:

   API_KEY: 'YOUR_ACTUAL_API_KEY',

3. Install Dependencies

npm install

4. Build TypeScript

# Build once
npm run build

# Or watch for changes during development
npm run watch

5. Run the Application

# Build and serve (recommended - automatically builds first)
npm start

# Or manually: build then serve
npm run build
python3 -m http.server 8000
# Then open http://localhost:8000

Project Structure

yc_jam/
├── index.html                      # Main HTML file with map container
├── tsconfig.json                   # TypeScript configuration
├── package.json                    # Dependencies and scripts
├── config.js                       # API key configuration (gitignored)
├── config.example.js               # Example config file
├── src/
│   ├── types.ts                    # TypeScript type definitions
│   ├── config.ts                   # Configuration (TypeScript)
│   ├── map-setup.ts                # Google Maps initialization
│   ├── app.ts                      # Main application logic
│   ├── places-service.ts           # Places API integration
│   ├── routes-service.ts           # Routes API integration
│   ├── places-aggregate-service.ts # Places Aggregate API
│   ├── geocoding-service.ts        # Geocoding API
│   └── roads-service.ts            # Roads API
├── dist/                           # Compiled JavaScript (generated)
└── README.md

Note: This project uses TypeScript. Source files are in src/, and compiled JavaScript is output to dist/.

Complete API Integration

The project now includes comprehensive integration with all Google Maps Platform APIs:

1. Places API (src/places-service.js)

• ✅ Text Search - Natural language place search (new Places API)
• ✅ Nearby Search - Find places near a location
• ✅ Place Details - Get detailed information about places
• ✅ Place Autocomplete - Autocomplete suggestions
• ✅ Walking Distance Filter - Filter places by walking time
• ✅ Advanced Filtering - Filter by open status, rating, price level

2. Routes API (src/routes-service.js)

• ✅ Get Routes - Calculate routes between locations
• ✅ Distance Matrix - Calculate distances and times for multiple points
• ✅ Route Optimization - Optimize multi-stop routes
• ✅ Walking Time - Get walking time between points
• ✅ Route Rendering - Display routes on the map

3. Places Aggregate API (src/places-aggregate-service.js)

• ✅ Search Nearby - Advanced place search with aggregation
• ✅ Count by Type - Count places by type in an area
• ✅ Density Insights - Analyze place density
• ✅ High Density Areas - Find areas with most places

4. Geocoding API (src/geocoding-service.js)

• ✅ Geocode - Convert addresses to coordinates
• ✅ Reverse Geocode - Convert coordinates to addresses
• ✅ Address Validation - Validate and standardize addresses

5. Roads API (src/roads-service.js)

• ✅ Snap to Roads - Snap GPS points to nearest roads
• ✅ Nearest Roads - Find nearest road segments
• ✅ Speed Limits - Get speed limit information
• ✅ Route Snapping - Clean up GPS tracking data

Usage Examples:

// Places Service
const placesService = window.mapOps.placesService;
const results = await placesService.textSearch('quiet cafés', {
    location: window.mapOps.userLocation,
    openNow: true
});

// Routes Service
const routesService = window.mapOps.routesService;
const route = await routesService.getRoute(
    origin, 
    destination, 
    { travelMode: 'WALK' }
);

// Places Aggregate Service
const aggregateService = window.mapOps.placesAggregateService;
const density = await aggregateService.countByType(
    location, 
    1000, 
    ['restaurant', 'cafe']
);

// Geocoding Service
const geocodingService = window.mapOps.geocodingService;
const location = await geocodingService.geocode('1600 Amphitheatre Parkway');

// Roads Service
const roadsService = window.mapOps.roadsService;
const snapped = await roadsService.snapToRoads(gpsPoints);

Next Steps

• Basic map setup
• Places API integration
• Routes API integration
• Places Aggregate API integration
• Geocoding API integration
• Roads API integration
• Implement NLP query parsing
• Connect search UI to all APIs
• Add result markers and info windows
• Implement route visualization
• Enhance UI with search results display

API Documentation

• Maps JavaScript API
• Places API
• Places Aggregate API
• Routes API
• Geocoding API
• Roads API

License

MIT