Using the Studio Data SDK, you can manage your map records with several map endpoints.

> 📘
>
> ### Note:   [Skip link to Note:](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#note)
>
> The Data SDK can be used to manage map records. For front-end visualizations, please refer to the Map SDK.

* * *

# Create Map   [Skip link to Create Map](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#create-map)

Create a new [map record](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map). When creating a map record, you can configure the [map's state](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map-state) via a JSON object.

PythonCLIHTTP

```python
studio_map = data_sdk.create_map(
    name="map name",
    description="map description",
    map_state = {
      "id": "56bd843f-d5a8-4448-8e8c-e63432b3c8dc",
      "data": {
          "bearing": 0,
          "dragRotate": False,
          "latitude": 39.72295394218594,
          "longitude": -94.31115944987631,
          "pitch": 0,
          "zoom": 5.202306331513537,
          "isSplit": False,
          "isViewportSynced": True,
          "isZoomLocked": False,
          "splitMapViewports": [],
          "mapViewMode": "MODE_2D",
          "mapSplitMode": "SINGLE_MAP",
          "globe": {
            "enabled": False
        }
      }
    },
    datasets = ['654ab82a-9c1a-478d-b888-a27a30c860a9']
)
```

```shell
fsq-data-sdk create-map \
      --name "map name" \
      --description "map description" \
      --map-state /path/to/map-state.json \
      --dataset-ids <uuid1>,<uuid2>
```

```http
curl -X POST https://data-api.foursquare.com/v1/maps/ \ 
  -H 'Authorization: Bearer <token>' \ 
  -H 'Content-Type: application/json' \ 
  --data-binary '@/path/to/my_map.json'
```

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#create_map)

* * *

# Copy Map   [Skip link to Copy Map](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#copy-map)

Creates a copy of an existing [map](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map), duplicating its layers and map state. Copy a map to create a snapshot of an existing project, build a "branch" of a project, or a template from which to start a new visualization.

You must choose whether to clone the target map's datasets (`copy_datasets = True`) or point to them as a data source (`copy_datasets = False`) for the cloned map.

- When creating a static snapshot of the original map, copying the datasets preserves the original context of the target project. However, if your new project relies on the same continually-updated datasets (e.g. a dataset containing weather measurements), you may want to point to the original datasets as a source for your new project.

- When creating a template from a map (i.e., cloning a map for its layer and map configuration), you should not copy its datasets to preserve space on your Studio Cloud account.

PythonCLIHTTP

```python
studio_map = data_sdk.copy_map(
      map = "<uuid>",
      copy_datasets = True,
      name = "My Copied Map Example")
```

```shell
fsq-data-sdk copy-map \
      --map-id "<uuid>" \
      --copy-datasets/--no--copy--datasets \
      --name "My Copied Map Example"
```

```http
curl --request POST \
     --url https://data-api.foursquare.com/v1/maps/<uuid>/copy \
     --header 'Authorization: Bearer <Token> \ 
     --header 'accept: application/json' \ 
     --header 'content-type: application/json' \ 
     --data '
{
  "copyDatasets": true,
  "name": "map_copy"
}
'
```

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#copy_map)

* * *

# Replace Dataset   [Skip link to Replace Dataset](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#replace-dataset)

Replace a dataset on a [map](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map), updating the visualization with the data from the new dataset. You can use this feature to apply a dataset with similar data on top of an existing project, visualizing the dataset with the existing map configuration. Alternatively, you can combine this function with [`copy_map`](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#copy_map) to use a map as a template, allowing you to create several new projects from a single map and several similar datasets.

> ⚠️
>
> ### Warning!   [Skip link to Warning!](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#warning)
>
> By default, this function expects a dataset with a compatible schema. At minimum, any columns used by map layers etc must be present and of the same type. For managed and hextile datasets, `replace_dataset` will check the schemas and will error if the new dataset is not compatible with the old one. To override the error, set `force = True`. To use strict type checking between fields, set `strict=True`. For other types of dataset, replacing a dataset with another one with an incompatible schema might cause your map's layers, filters, charts, etc to fail to render.

PythonCLIHTTP

```python
studio_map = data_sdk.replace_dataset(
      "38bbed5-eb0e-4c65-8bcc-cc173dc497qb", # Map UUID
      dataset_to_replace = "750dfn07-f8b9-4d37-b698-bacd1d8e6156",
      dataset_to_use =  "c9ff8f3e-8821-4k68-b7fc-94cb95fe65e2"
)
```

```shell
fsq-data-sdk replace-dataset \
      --map-id "38bbed5-eb0e-4c65-8bcc-cc173dc497qb" \
      --dataset-to-replace "750dfn07-f8b9-4d37-b698-bacd1d8e6156" \
      --dataset-to-use "c9ff8f3e-8821-4k68-b7fc-94cb95fe65e2" \
```

```http
curl --request POST \
     --url https://data-api.foursquare.com/v1/maps/<uuid>/datasets/replace \
     --header 'Authorization: Bearer <Token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "datasetToReplaceId": "dataset_1",
  "datasetToUseId": "dataset_2",
  "force": false,
  "strict": false
}
'
```

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#replace_dataset)

* * *

# Get Map   [Skip link to Get Map](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#get-map)

Get a [map record](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map). Pass the [UUID](https://docs.foursquare.com/developer/docs/studio-data-sdk-get-started#uuids) of the map record to receive the map's record as a JSON object.

PythonCLIHTTP

```python
studio_map = data_sdk.get_map_by_id("<uuid>")
```

```shell
fsq-data-sdk get-map <uuid>
```

```http
curl -X GET https://data-api.foursquare.com/v1/maps/<uuid> \ 
  -H 'Authorization: Bearer <token>'
```

The response contains the map's metadata, its entire configuration stored in `latest_state`, as well as an array of datasets associated with the map.

JSON

```json
{
  "id": "string",
  "name": "string",
  "createdAt": "2020-11-03T21:27:14.000Z",
  "updatedAt": "2020-11-13T01:44:07.000Z",
  "description": "string",
  "privacy": "private",
  "permission": "editor",
  "latestState": {
    ...
  },
  "datasets": [
    {
      "id": "string",
      "name": "string",
      "createdAt": "2020-11-10T18:09:39.000Z",
      "updatedAt": "2020-11-10T18:09:39.000Z",
      "privacy": "private",
      "permission": "editor",
      "isValid": true
    }
  ]
}
```

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#get_map_by_id)

* * *

# Update Map   [Skip link to Update Map](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#update-map)

Update an existing [map record](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map), locating the map with its [UUID](https://docs.foursquare.com/developer/docs/studio-data-sdk-get-started#uuids). When updating a map record, you can configure the map's state via a JSON object.

You can retrieve a map's configuration using the [Get Map](https://docs.foursquare.com/developer/docs/data-sdk-map-functions#get-map) function. Modify the JSON configuration stored in the `latest_state`, save it a new JSON file, then pass it via the `update_map` function.

> Note: If you are updating a critical map, [copy it](https://docs.foursquare.com/developer/docs/data-sdk-map-functions#copy-map) prior to updating the configuration.

PythonCLIHTTP

```python
data_sdk.update_map(
    map_id = map.id,
    map_state = {
        "id": map.latest_state.id,
        "data": map.latest_state.data
    }
)
```

```shell
fsq-data-sdk update-map \
      --map-id "map-uuid" \
      --name "new name" \
      --description "new description" \
      --map-state map-state.json \
      --dataset-ids <uuid1>,<uuid2>
```

```http
curl -X PUT https://data-api.foursquare.com/v1/maps/<uuid> \ 
    -H 'Authorization: Bearer <token>' \ 
    -H 'Content-Type: application/json' \ 
    --data-binary '@/path/to/my_map.json'
```

View map configuration specifications in the [map and layer format documentation](https://docs.foursquare.com/developer/docs/studio-map-layer-format).

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#update_map)

* * *

# Delete Map   [Skip link to Delete Map](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#delete-map)

Delete a map record. Pass the [UUID](https://docs.foursquare.com/developer/docs/studio-data-sdk-get-started#uuids) of the map to delete the map record. This will _not_ delete datasets associated with the map.

> ❗️
>
> ### Warning!   [Skip link to Warning!](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#warning-1)
>
> This operation cannot be undone.

PythonCLIHTTP

```python
data_sdk.delete_map("<uuid>")
```

```shell
fsq-data-sdk delete-map <uuid>
```

```http
curl -X DELETE https://data-api.foursquare.com/v1/maps/<uuid> \ 
  -H 'Authorization: Bearer <token>'
```

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#delete_map)

* * *

# List Maps   [Skip link to List Maps](https://docs.foursquare.com/developer/docs/data-sdk-map-functions\#list-maps)

List all [map records](https://docs.foursquare.com/developer/docs/studio-data-sdk-classes#map) on the authorized account.

PythonCLIHTTP

```python
maps = data_sdk.list_maps()
```

```shell
fsq-data-sdk list-maps
```

```http
curl -X GET https://data-api.foursquare.com/v1/maps HTTP/1.1 \ 
    -H 'Authorization: Bearer <token>'
```

If you are part of an organization, you can pass the organization parameter to get all map records for the organization of the authorized account.

PythonCLIHTTP

```python
maps = data_sdk.list_maps(organization = True)
```

```shell
fsq-data-sdk list-maps --organization
```

```http
curl -X GET https://data-api.foursquare.com/v1/maps/for-organization HTTP/1.1 \ 
    -H 'Authorization: Bearer <token>'
```

[Learn more in the SDK reference](https://docs.foursquare.com/developer/docs/studio-data-sdk-reference#list_maps)

Updated 5 months ago

* * *