Get a dataset
AI-generated Key Takeaways
After creating and uploading data to a dataset, you can access it using HTTP GET requests to list all datasets, retrieve information about a specific dataset, or download the dataset data.
When data is successfully uploaded, it creates a new, active version of the dataset, which is the version used by your application.
You can retrieve details for all datasets or filter by the active version using specific API endpoints and parameters.
Downloading a dataset involves sending a GET request to a dedicated endpoint, specifying the dataset ID and desired output location.
After you create a dataset and upload data to it, you can use HTTP GET requeststo 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 datafrom a dataset.
About dataset versions
After a successful data upload, the state of the dataset is set toSTATE_COMPLETED and that dataset becomes theactive version. That means thedataset is ready to use in your app. To determine thestate 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 thedataset:
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 versionstays as the "active" version and is the version used by your app.
For more information about creating a new version of a dataset, seeUpload new data to the dataset.
List all datasets
List all datasets by sending an HTTPGET request to thelist 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 tolist the active version of each dataset, append thetag=active query parameterto 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 alldatasets:
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 HTTPGET request to theget dataset endpoint that alsoincludes 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 informationabout the active version of the dataset, append the@active tag to therequest:
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 HTTPGETrequest to thedownload datasetendpoint 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' \--outputLOCAL_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 thecURL --output option to specify the name of thefile that holds the downloaded data. For example, the following--output flagspecifies to download the dataset to a file namedmyjson.json in the samedirectory used to run thecURL command:
--output myjson.json
Or use the following flag to download the data tomyjson.json in the/tmpdirectory:
--output /tmp/myjson.json
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-11-21 UTC.