Create and manage a dataset

Datasets let you upload geospatial data from a local file or from Google Cloud Storage to the Google Maps Platform. You can then associate a dataset with one or more map styles in the Cloud Console. After associating the dataset with a maps style, use the data-driven styling API to dynamically style your maps application.

You can also use a REST API to upload your geospatial data to a dataset. For more information, seeMaps Datasets API

Configure roles

To create and manage datasets in a Google Cloud project, you must hold either the Owner or Editor IAM role on the project.

Alternatively, you can assign the following IAM roles to a user account or service account that you use to manage datasets:

• TheMaps Platform Datasets Adminrole grants the user or services account read/write access to datasets in the project. This role lets the user perform all operations on a dataset.
• TheMaps Platform Datasets Viewerrole grants read-only access to datasets in the project. This role lets you perform a list, get, or download operation on a dataset.

For more information, see Grant an IAM role by using the Google Cloud console.

Data source for a dataset

• When uploading data from Cloud Storage, specify the file path to the resource containing the data in Cloud Storage. This path is in the form gs://GCS_BUCKET/FILE.

  The user making the request requires theStorage Object Viewer role, or any other role that includes thestorage.objects.getpermission. For more information about managing access to Cloud Storage, see Overview of access control.

• When uploading data from a local file, specify the path to the GeoJSON, KML, or CSV file containing the data to upload.

Prerequisites

When creating a dataset:

• Display names must be unique within your Google Cloud project.
• Display names must be less than 64 bytes (Because these characters are represented in UTF-8, in some languages each character can be represented by multiple bytes).
• Descriptions must be less than 1000 bytes.

When uploading data:

• The supported file types are CSV, GeoJSON, and KML.
• The maximum supported file size is 500 MB.
• Attribute column names cannot begin with the string "?_".
• Three-dimensional geometries are not supported. This includes the "Z" suffix in the WKT format, and the altitude coordinate in the GeoJSON format.

Data preparation best practices

If your source data is complex or large, such as dense points, long linestrings or polygons (often source file sizes larger than 50 MB fall into this category), consider simplifying your data before uploading to achieve the best performance in a visual map.

Here are some best practices for preparing your data:

1. Minimize feature properties.Only keep feature properties needed to style your map, for example "id" and "category". You can join additional properties to a feature in a client application using data-driven styles on a unique identifier key. For example, see See your data in real time with Data-driven styling.
2. Use simple data typesfor property objects where possible, such as integers, to minimize tile size and improve map performance.
3. Simplify complex geometriesprior to uploading a file. You can do this in a geospatial tool of your choice, such as the open source Mapshaper.orgutility, or in BigQuery using ST_Simplify on complex polygon geometries.
4. Cluster very dense pointsprior to uploading a file. You can do this in a geospatial tool of your choice, such as the open source turf.js cluster functions,or in BigQuery usingST_CLUSTERDBSCAN on dense point geometries.

See additional guidance about datasets best practices in Visualize your data with Datasets and BigQuery.

GeoJSON requirements

Maps JavaScript API supports the current GeoJSON specification. Maps JavaScript API also support GeoJSON files that contain any of the following object types:

• Geometry objects.A geometry object is a spatial shape, described as a union of points, lines, and polygons with optional holes.
• Feature objects.A feature object contains a geometry plus additional name/value pairs, whose meaning is application-specific.
• Feature collections.A feature collection is a set of feature objects.

Maps JavaScript API does not support GeoJSON files that have data in a coordinate reference system (CRS) other thanWGS84.

For more information on GeoJSON, see RFC 7946 compliant.

KML requirements

Maps JavaScript API has the following requirements:

• All URLs must be local (or relative) to the file itself.
• Point, line, and polygon geometries supported.
• All data attributes are considered strings.

• Icons or<styleUrl>defined outside of the file.
• Network links, such as<NetworkLink>
• Ground overlays, such as<GroundOverlay>
• 3D geometries or any altitude-related tags such as<altitudeMode>
• Camera specifications such as<LookAt>
• Styles defined inside the KML file.

CSV requirements

For CSV files, the supported column names are listed below in order of priority:

• latitude,longitude
• lat,long
• x,y
• wkt(Well-Known Text)
• address,city,state,zip
• address
• A single column containing all address information, such as 1600 Amphitheatre Parkway Mountain View, CA 94043

For example, your file contains columns namedx,y,andwkt. Becausexandyhave a higher priority, as determined by the order of supported column names in the list above, the values in thexandycolumns are used and thewktcolumn is ignored.

In addition:

• Each column name must belong to a single column. That is, you cannot have a column named xythat contains both x and y coordinate data. The x and y coordinates must be in separate columns.
• Column names are case-insensitive.
• The order of the column names does not matter. For example, if your CSV file contains latandlongcolumns, they can occur in any order.

Handle data upload errors

When uploading data to a dataset, you might experience one of the common errors described in this section.

GeoJSON errors

Common GeoJSON errors include:

• Missingtypefield, or thetypeis not a string. The uploaded GeoJSON data file must contain a string field namedtypeas part of each Feature object and Geometry object definition.

KML errors

Common KML errors include:

• The data file must not contain any of the unsupported KML features listed above, otherwise the data import might fail.

CSV errors

Common CSV errors include:

• Some rows are missing values for a geometry column. All rows in a CSV file must contain non-empty values for the geometry columns. The geometry columns include:
  • latitude,longitude
  • lat,long
  • x,y
  • wkt
  • address,city,state,zip
  • address
  • A single column containing all address information, such as 1600 Amphitheatre Parkway Mountain View, CA 94043
• Ifxandyare your geometry columns, ensure that the units are longitude and latitude. Some public datasets use different coordinate systems under the headers xandy.If the wrong units are used, the dataset might import successfully, but the rendered data can show the dataset points in unexpected locations.

Create a dataset

To create a dataset:

1. In the Google Cloud Console,go to theDatasetspage.
2. ClickCreate Dataset.
3. Enter the dataset name. The name must be unique among all datasets.
4. Optionally enter a datasetDescription.
5. ClickContinue.TheImport datapage appears.
6. Select theUpload sourceof the data used to populate the dataset as Desktop,meaning a local file on your system, or Google Cloud Storage bucket.
   • ForDesktop,clickBrowseand then select the file from the file chooser.
   • ForGoogle Cloud Storage bucket,clickBrowseand select the bucket and file containing the data.
7. Select theFile format.
8. ClickContinueto review your settings.

9. ClickCreate.TheDatasetspage appears showing your new dataset. The status should beProcessing.

   If the data uploads successfully:

   • The status of the dataset is set toCOMPLETED.
   • The dataset becomes the "active" version and is the version used by your app.

   If there is an error in the upload:

   • The status of the new dataset version is set to a status other than COMPLETED.

View or modify a dataset

After you create a dataset, you can view or modify the dataset:

1. In the Google Cloud Console,go to theDatasetspage.
2. Click the name of the dataset. TheDataset detailspage appears.
   1. Click theDetailstab to see information about the dataset. On this tab you can also edit the dataset name and description.
   2. Click thePreviewtab to see your dataset on a map (datasets with a state ofCOMPLETEDorREVERTEDonly).
   3. Click theTable Datatab to see all attributes of the dataset (datasets with a state ofCOMPLETEDorREVERTEDonly). These are the attributes that you can use to style the dataset on the map.
   4. Click theDownloadbutton to download the data to a local file.
   5. Click theDeletebutton to delete the dataset.

   6. Click theImport Data Filebutton to upload new data to the dataset.

      Uploading new data to the dataset creates a new version of the dataset. If the new data uploads successfully:

      • The status of the new version of the dataset is set toCOMPLETED.
      • The new version becomes the "active" version and is the version used by your app.

      If there is an error in the upload:

      • The status of the new dataset version is set to a status other than COMPLETED.For example, if there is a previous "active" version, the status of the dataset is set toREVERTED.
      • The previously "active" dataset version stays as the "active" version and is the version used by your app.