Site Administrators can use Spatial Lens to make custom choropleth maps available for Data Lens pages. These custom choropleth maps allow users to view and interact with your data through a localized lens. Find out more about Data Lens visualizations here.
There are a few steps to adding a custom choropleth map to Data Lens pages on your domain. First, a site administrator must configure the new Custom Boundary to be available for all Data Lens pages on the site. Then, the new Custom Boundary needs to be added to each Data Lens page by a user with permissions to edit the source dataset.
- Identifying your Spatial Lens Boundary
- Configuring a new Spatial Lens Boundary
- Adding a new Boundary to a Data Lens page
Identifying your Spatial Lens Boundary
In order to create a custom choropleth with Spatial Lens, you need to identify the Geospatial file for the boundary that you want to configure and upload it to your Socrata site via the Geopatial Import Wizard.
A Geospatial File:
- Can be KML, KMZ, Shapefile or Geojson
- Must be a single layer map that contain polygons or multipolygons
- Should contain a label for each boundary in the map
The label for each boundary is needed so that users can identify the area that they are looking at on the map. For example, a USA States boundary map would have labels such as Alabama, Alaska, Arizona, etc. These labels must be contained within a column in the geospatial file. You can find the label column in the attribute table for your geospatial file. Once uploaded to Socrata, this table can be viewed by selecting the “table view” on the map.
Configuring a new Spatial Lens Boundary
Once the geospatial file has been uploaded to your Socrata site, you are ready to start configuring it for Spatial Lens. You’ll need an Administrator role to use the Spatial Lens configuration Panel.
- Navigate to Spatial Lens from the Administration Panel of your Open Data Site.
- Click “Add New” to open the Spatial Lens picker. In the picker, find the boundary map and click the “Choose” button next it. Clicking on the name of the dataset will let you look at the map.
If you are not able to find the boundary map, check out this articles for tips on Why does my boundary map is not showing up in the Spatial Lens picker?
- On the next screen, give your Spatial Lens Boundary a name and pick the column that should represent the label for the shapes. By default the Boundary Name is the Dataset Title, this can be edited. The Boundary Name is in the title of the Choropleth when added to a Data Lens page, so it is important that this name is human readable and will allow users to identify area and regions that the map represents.
If needed, this Boundary name & the label column that you choose can be changed later. A Boundary Name can only be used one time on a domain, and Boundaries cannot be otherwise edited.
Your new Spatial Lens should now appear in the Custom Boundaries list. You’ll see a few different options next to your Boundary name:
- Enable/Disable - When a Spatial Lens Boundary is enabled it is available to use to make a choropleth mao on your site’s Data Lens pages. When it is disabled, it does not show in the list of available boundaries for Data Lens publishers to choose from.
- Auto Encode on Ingress - Choosing this option saves you time and effort. If there is a choropleth that your users will want on most of their Data Lens pages, then choose this option. This means that the Spatial Lens Boundary will automatically be available on every new dataset that is uploaded to your site while this box is checked. You can add up to 5 auto-encoded spatial lenses per domain.
- Edit - Once configured you can edit the boundary configuration and change the Boundary Name and/or pick a different column to be the label on the choropleth map. This changes will automatically go into effect on already created Data Lens pages.
If your Spatial Lens doesn’t appear on the list or you see an error message that “Something went wrong…,” please contact Socrata Support with error message code, and/or a screenshot of the error, along with your domain url and the link to the boundary map that you were trying to configure.
Adding a new Boundary to a Data Lens page
Once the Spatial Lens Boundary is configured, you’ll want to make it available to all Data Lens page publishers. To do this a site administrator, dataset owner, or anyone that is able to edit the source dataset must initialize the Spatial Lens Boundary on 1 Data Lens page for each dataset.
Anytime a new dataset is added to your site, unless “auto encode on ingress” was enabled when it was uploaded, you’ll need to initialize each custom Spatial Lens Boundary.
*Remember* map cards, including this new Boundary, only show on Data Lens pages that have a geocoded location column in their source dataset. If the dataset does not have a location column, you will not see the option to create a map of the data in Data Lens. Find out more about Data Lens visualizations here.
To initialize the Spatial Lens boundary for a dataset, enter “customize mode” on a Data Lens page for that dataset.
- Add a new card and choose the location column from the drop down list
- Choose Choropleth card type
- From the list of boundaries, choose the newly added boundary.
You’ll see a message “Add this card to the page to begin computing this visualization.”
- Add the card to the Data Lens page to initialize it and make it available to publisher for every Data Lens page made from that same source dataset.
- The card will show in customize mode on Data Lens page with message “This visualization is being computed. Check back in a few minutes.” This means that the process has started.
You can stay on the page and the choropleth will show when ready, usually just a few moments or you can save the page, close the tab and the computing will continue. The choropleth will render as expected on the next page reload as long as it is done computing.
Now, whenever any users add a choropleth card to Data Lens pages created from this source dataset, they’ll have the option to use this boundary.
If you have trouble during this step, please contact Socrata support, include screenshot for the issue that you see, a link to Data Lens page where you experience difficulty and the name of the boundary that you were attempting to use.