# Maps JavaScript API
## What It Does
The Maps JavaScript API lets you embed fully customizable interactive maps into websites. Users can pan, zoom, click markers, draw shapes, and interact with custom data layers. It's the foundation for building location-based web applications.
Unlike simple embedded maps, this API gives you programmatic control over every visual element and user interaction.
## Music Use Case: Interactive Audio Maps
Transform static playlists into geographic experiences:
**Soundwalk websites:**
- Place markers at field recording locations
- Click marker → play audio clip from that spot
- Draw routes showing the path through sonic space
- Add info windows with recording notes, equipment used, weather conditions
**Example:** Tijuana Music Scene Map
```javascript
// Initialize map centered on Zona Centro
const map = new google.maps.Map(document.getElementById("map"), {
center: {lat: 32.5307, lng: -117.0366},
zoom: 15,
mapId: "tijuana_music_scene"
});
// Add venue markers with audio players
const venues = [
{
name: "Tijuana Jazz Club",
coords: {lat: 32.5327, lng: -117.0363},
audio: "recordings/jazz-club-friday-night.mp3",
description: "Friday night jazz trio, recorded 2025-11-01"
},
{
name: "Black Box",
coords: {lat: 32.5307, lng: -117.0366},
audio: "recordings/black-box-experimental.mp3",
description: "Experimental electronic set, 2025-10-15"
}
];
venues.forEach(venue => {
const marker = new google.maps.Marker({
position: venue.coords,
map: map,
title: venue.name
});
const audioPlayer = `
<h3>${venue.name}</h3>
<p>${venue.description}</p>
<audio controls src="${venue.audio}"></audio>
`;
const infoWindow = new google.maps.InfoWindow({content: audioPlayer});
marker.addListener("click", () => {
infoWindow.open(map, marker);
});
});
```
**Venue discovery tools:**
- Interactive directory of music venues, studios, instrument shops
- Filter by genre, capacity, equipment available
- Click venue → see photos, reviews, upcoming shows
- Integrate with Places API for real-time data
**Tour routing:**
- Visualize multi-city tour routes
- Show driving times between venues
- Plan itineraries with Directions API integration
- Share interactive tour maps with fans
## Environmental Research Use Case: Infrastructure Visualization
Make complex water systems understandable through interactive mapping:
**Water treatment network mapping:**
- Plot treatment plants, pump stations, monitoring sites
- Color-code by capacity, condition, or priority
- Click facility → see operational data, inspection reports
- Draw service area polygons
**Example:** Tijuana Water Infrastructure Dashboard
```javascript
const map = new google.maps.Map(document.getElementById("map"), {
center: {lat: 32.4850, lng: -116.9500},
zoom: 11,
mapId: "tijuana_water_infrastructure"
});
// Treatment plants with operational data
const plants = [
{
name: "WWTP La Morita",
coords: {lat: 32.4552, lng: -116.8605},
capacity: "25 MGD",
status: "operational",
elevation: "122.9m",
lastInspection: "2025-10-15"
},
{
name: "San Antonio de los Buenos",
coords: {lat: 32.4698, lng: -117.0828},
capacity: "15 MGD",
status: "operational",
elevation: "101.5m",
lastInspection: "2025-09-22"
}
];
plants.forEach(plant => {
const marker = new google.maps.Marker({
position: plant.coords,
map: map,
icon: {
path: google.maps.SymbolPath.CIRCLE,
scale: 10,
fillColor: plant.status === "operational" ? "#4CAF50" : "#FF5252",
fillOpacity: 0.8,
strokeWeight: 2,
strokeColor: "#FFF"
}
});
const info = `
<h3>${plant.name}</h3>
<p><strong>Capacity:</strong> ${plant.capacity}</p>
<p><strong>Elevation:</strong> ${plant.elevation}</p>
<p><strong>Status:</strong> ${plant.status}</p>
<p><strong>Last Inspection:</strong> ${plant.lastInspection}</p>
`;
const infoWindow = new google.maps.InfoWindow({content: info});
marker.addListener("click", () => infoWindow.open(map, marker));
});
// Add service area polygon
const serviceArea = new google.maps.Polygon({
paths: [...coordinates...],
strokeColor: "#2196F3",
strokeOpacity: 0.8,
strokeWeight: 2,
fillColor: "#2196F3",
fillOpacity: 0.2
});
serviceArea.setMap(map);
```
**Water quality monitoring:**
- Map sampling locations with color-coded water quality indicators
- Time-series visualization (slider to show quality over time)
- Click site → see historical data charts
- Draw pollution corridors or watershed boundaries
**Sewer system inspection routing:**
- Display sewer lines, manholes, inspection priorities
- Highlight areas needing attention (red = urgent, yellow = monitor)
- Plan inspection routes with distance calculations
- Real-time crew location tracking (with Geolocation API)
## How to Use It
### Basic Setup
**1. Load API in HTML:**
```html
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
```
**2. Create map container:**
```html
<div id="map" style="height: 600px; width: 100%;"></div>
```
**3. Initialize map in JavaScript:**
```javascript
function initMap() {
const map = new google.maps.Map(document.getElementById("map"), {
center: {lat: 32.5332, lng: -117.0192},
zoom: 12
});
}
```
### Key Features
**Markers:**
- Standard markers, custom icons, or SVG paths
- Draggable, animated, clustered
- Info windows with HTML content
**Shapes:**
- Polylines (routes, paths)
- Polygons (service areas, zones)
- Circles (radius around point)
- Rectangles (bounding boxes)
**Custom styling (Map ID):**
```javascript
// Create Map ID in Cloud Console with custom style JSON
const map = new google.maps.Map(document.getElementById("map"), {
mapId: "your_custom_map_id", // Apply custom colors, hide roads, etc.
center: {lat: 32.5332, lng: -117.0192},
zoom: 12
});
```
**Data layers:**
```javascript
map.data.loadGeoJSON('water-infrastructure.geojson');
map.data.setStyle({
fillColor: '#2196F3',
strokeWeight: 2
});
```
## How It Works
**Client-side rendering:**
- Map tiles loaded from Google's CDN
- JavaScript handles interactions (pan, zoom, clicks)
- Markers and overlays rendered in browser
- No server needed (beyond hosting your HTML/JS)
**Tile-based system:**
- World divided into 256x256 pixel tiles at 23 zoom levels
- Zoom 0 = entire world in 1 tile
- Zoom 23 = individual buildings visible
- Browser requests only visible tiles (performance)
**Events:**
```javascript
map.addListener('click', (event) => {
console.log(event.latLng.lat(), event.latLng.lng());
});
marker.addListener('click', () => {
// Handle marker click
});
```
## When to Use It
**Music/Audio projects:**
- Interactive soundwalk websites
- Venue/studio directories
- Tour route visualization
- Field recording location documentation
**Environmental research:**
- Water/sewer infrastructure dashboards
- Monitoring site visualization
- Service area mapping
- Inspection route planning
**Use this instead of Maps Embed API when:**
- You need custom markers, shapes, or data layers
- You want user interactions (click, drag, draw)
- You need programmatic control (update map from code)
- You're building a data-driven web application
**Don't use it for:**
- Simple static maps (use Maps Embed API)
- Mobile apps (use Maps SDK for Android/iOS)
- Server-side rendering (use Maps Static API)
## Pro Tips
**Map IDs enable advanced styling:** Create themed maps (dark mode for audio players, high-contrast for accessibility, minimal for data focus).
**Cluster markers for performance:** With 100+ markers, use MarkerClusterer library to group nearby markers.
**GeoJSON for complex data:** Store infrastructure data, watershed boundaries, or venue networks in GeoJSON files. Load with `map.data.loadGeoJSON()`.
**Combine with other APIs:**
- Places API → Autocomplete location search
- Directions API → Draw routes between points
- Elevation API → Color-code terrain by elevation
- Street View API → Embed panoramas in info windows
**Lazy load audio:** Don't load all audio files at page load. Load when user clicks marker to save bandwidth.
**Mobile responsive:** Use viewport meta tag and CSS to make maps work on phones.
```html
<meta name="viewport" content="width=device-width, initial-scale=1.0">
```
## Real-World Example: Soundwalk Builder
**Complete workflow:**
1. User searches for location (Places Autocomplete)
2. Click map to add recording points
3. Upload audio file for each point
4. Draw polyline connecting points (suggested route)
5. Export shareable URL or embed code
6. Visitors click markers to hear soundscape journey
## Related APIs
- [[Maps Embed API]] - Simple embeddable maps without code
- [[Maps Datasets API]] - Store and manage custom geospatial data
- [[Street View Static API]] - Add ground-level photos to info windows
- [[Places API]] - Search for venues, studios, landmarks
- [[Directions API]] - Draw routes between markers
## Resources
- [Maps JavaScript API Documentation](https://developers.google.com/maps/documentation/javascript)
- [Map styling wizard](https://mapstyle.withgoogle.com/)
- [Code samples and tutorials](https://developers.google.com/maps/documentation/javascript/examples)
- MarkerClusterer library for performance