Get a dataset

After you create a dataset and upload data to it, you can use HTTP GET requests to access the dataset. This page describes how to list all of your datasets, how to get information about a specific dataset, and how to download the data from a dataset.

About dataset versions

After a successful data upload, the state of the dataset is set to STATE_COMPLETED and that dataset becomes the active version. That means the dataset is ready to use in your app. To determine the state of the dataset, you can either list all datasets or get a specific dataset.

You can upload new data to the dataset to create a new version of the dataset:

If the new data uploads successfully, the new version becomes the "active" version and is the version used by your app.
If there is an error in the upload, the previous successful dataset version stays as the "active" version and is the version used by your app.

For more information about creating a new version of a dataset, see Upload new data to the dataset.

List all datasets

List all datasets by sending an HTTP GET request to the list datasets endpoint:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

This request returns information about the latest version of all datasets, regardless of whether the version is the active version. If you only want to list the active version of each dataset, append the tag=active query parameter to the request:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets?tag=active

For example, this call returns information about the latest version of all datasets:

curl -X GET \
-H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
-H 'Authorization: Bearer $TOKEN' \
"https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets"

This call returns a response in the form:

{
  "datasets": [
    {
      "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46",
      "displayName": "My Test Dataset",
      "versionId": "5fb34e-1405-4ecd-8f81-31f1c07",
      "usage": [
        "USAGE_DATA_DRIVEN_STYLING"
      ],
      "gcsSource": {
        "inputUri": "gs://mybucket/my.csv",
        "fileFormat": "FILE_FORMAT_CSV"
      },
      "createTime": "2023-03-24T14:47:37.308977Z",
      "updateTime": "2023-03-24T14:48:05.053114Z",
      "versionCreateTime": "2023-03-24T14:48:05.053114Z",
      "status": {
        "state": "STATE_COMPLETED"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER_OR_ID/datasets/2c8ae479-96704-89c6435ca959",
      "displayName": "My Other Test Dataset",
      "versionId": "0d2e3-b9da-47cc-819f-7ac67562",
      "usage": [
        "USAGE_DATA_DRIVEN_STYLING"
      ],
      "localFileSource": {
        "fileFormat": "FILE_FORMAT_CSV"
      },
      "createTime": "2023-03-24T14:41:52.579755Z",
      "updateTime": "2023-03-24T14:42:56.784122Z",
      "versionCreateTime": "2023-03-24T14:42:56.784122Z",
      "status": {
        "state": "STATE_COMPLETED"
      }
    }
  ]
}

Get information about a dataset

To get information about a specific dataset, send an HTTP GET request to the get dataset endpoint that also includes the ID of the dataset:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID

This request returns information about the latest version of the dataset, regardless of whether the version is the active version. If you want information about the active version of the dataset, append the @active tag to the request:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@active

For example:

curl -X GET \
-H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
-H 'Authorization: Bearer $TOKEN' \
"https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46@active"

This request returns a response in the form:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46",
  "displayName": "My Test Dataset",
  "versionId": "5fb34e-1405-4ecd-8f81-31f1c07",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "gcsSource": {
    "inputUri": "gs://mybucket/my.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2023-03-24T14:47:37.308977Z",
  "updateTime": "2023-03-24T14:48:05.053114Z",
  "versionCreateTime": "2023-03-24T14:48:05.053114Z",
  "status": {
    "state": "STATE_COMPLETED"
  }
}

Download a dataset

To download the data from the latest version of a dataset, send an HTTP GET request to the download dataset endpoint that also includes the ID of the dataset:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:download?alt=media

For example:

curl -X GET -L \
-H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
-H 'Authorization: Bearer $TOKEN' \
--output LOCAL_LOCATION_TO_OUTPUT \
"https://mapsplatformdatasets.googleapis.com/download/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46:download?alt=media"

In this example, you use the cURL --output option to specify the name of the file that holds the downloaded data. For example, the following --output flag specifies to download the dataset to a file named myjson.json in the same directory used to run the cURL command:

--output myjson.json

Or use the following flag to download the data to myjson.json in the /tmp directory:

--output /tmp/myjson.json