# Maps Datasets API ## What It Does The Maps Datasets API lets you upload, store, and manage your own geospatial data (GeoJSON, KML, CSV with coordinates) in Google's cloud infrastructure, then render it on Google Maps. Your custom data becomes a first-class map layer alongside Google's base maps, roads, and places. Think of it as a spatial database with a visualization frontend. You upload data once, use it across Maps JavaScript API, mobile SDKs, and other Google Maps tools. ## Music Use Case: Audio Map Data Management Transform scattered field recording metadata into a structured, queryable spatial database: **Field recording catalog:** - Upload GeoJSON with recording locations, filenames, dates, equipment, conditions - Query recordings by location, date range, weather, or custom tags - Render on interactive maps without managing your own database - Share datasets with collaborators **Example GeoJSON structure:** ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-117.0363, 32.5327] }, "properties": { "name": "Tijuana Jazz Club - Friday Night Set", "recording_date": "2025-11-01T21:30:00Z", "equipment": "Zoom H6, Rode NTG3", "duration": "45:32", "audio_url": "https://audio.example.com/tj-jazz-2025-11-01.wav", "notes": "Live jazz trio, moderate audience noise", "weather": "Clear, 18°C, light winds", "uaqi": 42 } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-117.0366, 32.5307] }, "properties": { "name": "Black Box - Experimental Electronic", "recording_date": "2025-10-15T22:00:00Z", "equipment": "Zoom H6, Audio-Technica BP4025", "duration": "38:15", "audio_url": "https://audio.example.com/black-box-2025-10-15.wav", "notes": "Heavy bass, spatial audio recording", "weather": "Cloudy, 16°C", "uaqi": 55 } } ] } ``` **Upload to Maps Datasets API:** ```bash curl -X POST "https://mapsplatformdatasets.googleapis.com/v1alpha/projects/YOUR_PROJECT/datasets" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Tijuana Field Recordings 2025", "description": "Audio documentation of Tijuana music venues and urban soundscapes" }' # Then upload GeoJSON file to dataset curl -X POST "https://mapsplatformdatasets.googleapis.com/v1alpha/projects/YOUR_PROJECT/datasets/DATASET_ID:import" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputFormat": "GEO_JSON", "gcsSource": { "uri": "gs://your-bucket/tijuana-recordings.geojson" } }' ``` **Render on map:** ```javascript const map = new google.maps.Map(document.getElementById("map"), { center: {lat: 32.5307, lng: -117.0366}, zoom: 14, mapId: "audio_map" }); // Load dataset const datasetLayer = map.data; datasetLayer.loadDataset("projects/YOUR_PROJECT/datasets/DATASET_ID"); // Style based on properties datasetLayer.setStyle((feature) => { return { icon: { url: "/icons/audio-marker.png", scaledSize: new google.maps.Size(40, 40) } }; }); // Add click handler with audio player datasetLayer.addListener('click', (event) => { const props = event.feature.getProperty(); const infoWindow = new google.maps.InfoWindow({ content: ` <h3>${props.name}</h3> <p>Recorded: ${new Date(props.recording_date).toLocaleDateString()}</p> <p>Equipment: ${props.equipment}</p> <audio controls src="${props.audio_url}"></audio> <p>${props.notes}</p> ` }); infoWindow.setPosition(event.latLng); infoWindow.open(map); }); ``` **Venue network analysis:** - Upload venue locations with metadata (capacity, genres, equipment) - Query: "All venues within 2km of border crossing with live sound systems" - Visualize music scene density, genre clusters, tour routing ## Environmental Research Use Case: Infrastructure Data Management Centralize water/sewer infrastructure data for analysis and visualization: **Sewer infrastructure database:** - Upload sewer line geometries (LineString) with attributes (age, material, condition) - Upload manhole locations (Point) with inspection dates, depth, condition scores - Upload treatment plant polygons with operational data - Query for planning and analysis **Example dataset structure:** ```json { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-116.8605, 32.4552], [-116.8610, 32.4560], [-116.8615, 32.4568] ] }, "properties": { "line_id": "TJ-SW-1234", "type": "sewer_main", "diameter_mm": 450, "material": "PVC", "install_date": "2010-06-15", "last_inspection": "2025-08-20", "condition": "good", "priority": "routine", "flow_direction": "gravity", "upstream_facility": "WWTP La Morita" } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-116.8605, 32.4552] }, "properties": { "manhole_id": "MH-0423", "depth_m": 3.2, "last_inspection": "2025-08-20", "condition": "moderate_wear", "notes": "Sediment buildup, schedule cleaning", "priority": "medium" } } ] } ``` **Water quality monitoring sites:** - Upload sampling locations with historical data - Color-code by recent test results (green = safe, red = contaminated) - Query: "All sites with E. coli > 400 CFU/100ml in last 30 days" - Identify pollution patterns **Treatment plant service areas:** - Upload polygon boundaries for each plant's service area - Calculate population served, area covered - Overlay with elevation data to verify gravity flow design - Plan expansion or new facilities ## How to Use It ### Workflow **1. Create dataset:** ```bash curl -X POST "https://mapsplatformdatasets.googleapis.com/v1alpha/projects/YOUR_PROJECT/datasets" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Tijuana Water Infrastructure", "description": "Sewer lines, pump stations, treatment plants" }' ``` **2. Upload data:** - GeoJSON (recommended for complex geometries) - KML (for polygons and placemarks from Google Earth) - CSV with lat/lng columns (for simple points) **3. Render on map:** ```javascript // In Maps JavaScript API map.data.loadDataset("projects/YOUR_PROJECT/datasets/DATASET_ID"); // Style by properties map.data.setStyle((feature) => { const condition = feature.getProperty('condition'); return { strokeColor: condition === 'good' ? '#4CAF50' : condition === 'moderate_wear' ? '#FF9800' : '#F44336', strokeWeight: 3 }; }); ``` **4. Update data:** ```bash # Re-upload updated GeoJSON to replace dataset contents curl -X POST "https://mapsplatformdatasets.googleapis.com/v1alpha/projects/YOUR_PROJECT/datasets/DATASET_ID:import" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputFormat": "GEO_JSON", "gcsSource": {"uri": "gs://your-bucket/updated-data.geojson"} }' ``` ### Data Limits - Max dataset size: 5 GB - Max feature count: 1 million features per dataset - Max projects: 100 datasets per project - Geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon ## How It Works **Storage:** - Data stored in Google Cloud - Backed by Spanner (distributed SQL database) - Indexed for fast spatial queries **Rendering:** - Vector tiles generated automatically - Styled client-side (performance) - Works with all Google Maps SDKs **Updates:** - Replace entire dataset or append new features - Changes propagate to all maps using that dataset - No need to update individual map implementations ## When to Use It **Music/Audio projects:** - Managing 100+ field recording locations - Collaborative mapping (multiple contributors) - Versioned soundmap data (update once, render everywhere) - Complex queries (find all recordings in date range) **Environmental research:** - Infrastructure asset management - Water quality monitoring networks - Service area planning - Historical tracking (update dataset over time) **Use this instead of loading GeoJSON directly when:** - Data exceeds 10 MB (too large for client-side loading) - Multiple maps/apps use the same data - Data updates frequently (centralized updates) - You need spatial queries server-side **Don't use it for:** - Small datasets (<100 features) - just use `map.data.loadGeoJSON()` - Real-time data (updates take minutes to propagate) - Data that changes per user (user-specific overlays) ## Pro Tips **Use properties for filtering:** ```javascript map.data.addListener('addfeature', (event) => { // Only show high-priority features if (event.feature.getProperty('priority') !== 'high') { map.data.remove(event.feature); } }); ``` **Combine multiple datasets:** ```javascript map.data.loadDataset("projects/YOUR_PROJECT/datasets/sewer-lines"); map.data.loadDataset("projects/YOUR_PROJECT/datasets/treatment-plants"); map.data.loadDataset("projects/YOUR_PROJECT/datasets/monitoring-sites"); ``` **Version control with Cloud Storage:** Store GeoJSON in Git, upload to GCS on updates, trigger dataset refresh via API. **Generate GeoJSON from field data:** - Export from QGIS, ArcGIS, or other GIS tools - Convert from Shapefile: `ogr2ogr -f GeoJSON output.json input.shp` - Script from CSV: Add geometry objects to CSV rows **Validate GeoJSON before upload:** Use [geojson.io](http://geojson.io) or `geojsonhint` tool to catch errors. ## Real-World Example: Tijuana Water Quality Network **Workflow:** 1. Field crews collect water samples at 50 sites across Tijuana River watershed 2. Lab analysis produces CSV with site_id, lat, lng, e_coli, turbidity, date 3. Script converts CSV → GeoJSON with color-coded properties 4. Upload to Maps Datasets API 5. Dashboard loads dataset, colors markers by contamination level 6. Public health officials query for sites needing action 7. Monthly re-upload with updated test results **Result:** Centralized spatial database, no custom backend needed, automatic map updates. ## Integration with Database Workflows For serious GPS data management, consider integrating Maps Datasets API with a database backend: **Convex + Maps Datasets Workflow:** - Store GPS objects in Convex with rich metadata - Generate embeddings for semantic search - Sync to Maps Datasets API for visualization - Export to GeoJSON for version control See the [[07. GPS Dataset Catalog/]] folder for complete implementation guides: - [[GPS Dataset Architecture with Convex]] - Database schema for GPS objects - [[Syncing Maps Datasets API with Convex]] - Bidirectional sync workflows - [[Semantic Search for GPS Objects]] - Natural language search with embeddings - [[Building a GPS Dataset Manager]] - React component for CRUD operations **Why use a database backend:** - **Semantic search** - Find "recordings with heavy bass" without exact keyword matches - **Real-time collaboration** - Multiple users editing datasets simultaneously - **Rich metadata** - Store audio files, equipment specs, weather conditions - **Version control** - Track changes over time with Git integration - **Incremental sync** - Only upload changed objects, not entire dataset ## Related APIs - [[Maps JavaScript API]] - Render datasets on web maps - [[Places API]] - Enrich datasets with nearby place data - [[Elevation API]] - Add elevation to point datasets - Google Cloud Storage - Host GeoJSON files for import ## Resources - [Maps Datasets API Documentation](https://developers.google.com/maps/documentation/datasets) - [GeoJSON specification](https://geojson.org/) - [QGIS](https://qgis.org/) - Open-source GIS for data preparation - [geojson.io](http://geojson.io) - Visual GeoJSON editor