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. 

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']
)

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'

Learn more in the SDK reference

🧪

Try it now in the interactive API explorer

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 --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

🧪

Try it now in the interactive API explorer

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.

⚠️

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.

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"
)

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 --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

🧪

Try it now in the interactive API explorer

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>'

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.

{
  "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

🧪

Try it now in the interactive API explorer

Update Map

Update an existing map record, locating the map with its UUID. 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 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 prior to updating the configuration.

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'

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

Learn more in the SDK reference

🧪

Try it now in the interactive API explorer

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>'

Learn more in the SDK reference

🧪

Try it now in the interactive API explorer

List Maps

List all map records on the authorized account.

maps = data_sdk.list_maps()

uf-data-sdk list-maps

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.

maps = data_sdk.list_maps(organization = True)

uf-data-sdk list-maps --organization

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

🧪

Try it now in the interactive API explorer

Updated about 1 month ago