Maps Datasets API

Path: Computer Tech/Development/Tech Companies/Google/Google Maps Platform/Maps APIs/Maps Datasets API.mdUpdated: 2/3/2026

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↗ or geojsonhint tool to catch errors.

Real-World Example: Tijuana Water Quality Network

Workflow:

Field crews collect water samples at 50 sites across Tijuana River watershed
Lab analysis produces CSV with site_id, lat, lng, e_coli, turbidity, date
Script converts CSV → GeoJSON with color-coded properties
Upload to Maps Datasets API
Dashboard loads dataset, colors markers by contamination level
Public health officials query for sites needing action
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↗
GeoJSON specification↗
QGIS↗ - Open-source GIS for data preparation
geojson.io↗ - Visual GeoJSON editor