SupportLog In

Map Functions

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

📘

Note:

The Data SDK can be used to manage map records. For front-end visualizations, please refer to the Studio Map SDK.

Create Map

Create a new map record. When creating a map record, you can configure the map's state via a JSON object.
View map configuration specifications in the map and layer format documentation.

studio_map = data_sdk.create_map(
      name="map name",
      description="map description",
      map_state = {
        "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=['<uuid1>', '<uuid2>'])

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

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'

create_map reference

Copy Map

Creates a copy of an existing 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.

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

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

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

copy_map reference

Replace Dataset

Replace a dataset on a 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 to use a map as a template, allowing you to create several new projects from a single map and several similar datasets.

By default, this function expects a dataset with an identical schema and will error if the new dataset is not compatible with the old one. To override the error, set force = True.

studio_map = data_sdk.copy_map(
      map_id = "38bbed5-eb0e-4c65-8bcc-cc173dc497qb",
      dataset_to_replace = "750dfn07-f8b9-4d37-b698-bacd1d8e6156",
      dataset_to_use =  "c9ff8f3e-8821-4k68-b7fc-94cb95fe65e2"

uf-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" \

curl -X POST https://data-api.foursquare.com/v1/maps/<uuid>/datasets/replace \
    -H 'Authorization: Bearer <token>' \

replace_dataset reference

Get Map

Get a map record. Pass the UUID of the map record to receive the map's record as a JSON object.

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

uf-data-sdk get-map <uuid>

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

get_map_by_id reference

Update Map

Update an existing map record. When updating a map record, you can configure the map's state via a JSON object.

View map configuration specifications in the map and layer format documentation.

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

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

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'

update_map reference

Delete Map

Delete a map record. Pass the UUID of the map to delete the map record. This will not delete datasets associated with the map.

❗️

Warning!

This operation cannot be undone.

data_sdk.delete_map("<uuid>")

uf-data-sdk delete-map <uuid>

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

delete_map reference

List Maps

List all map records on the authorized account.

maps = data_sdk.list_maps()

uf-data-sdk list-maps

GET https://data-api.foursquare.com/v1/maps HTTP/1.1

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.

maps = data_sdk.list_maps(organization = True)

uf-data-sdk list-maps --organization

GET https://data-api.foursquare.com/v1/maps/for-organization HTTP/1.1

list_maps reference

Updated about 2 months ago