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 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']
)
fsq-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
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")
fsq-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
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_datasetwill check the schemas and will error if the new dataset is not compatible with the old one. To override the error, setforce = True. To use strict type checking between fields, setstrict=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"
)
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" \
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
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>")
fsq-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
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
}
)
fsq-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
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>")
fsq-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
List Maps
List all map records on the authorized account.
maps = data_sdk.list_maps()
fsq-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)
fsq-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
Updated 5 months ago