theopensystemslab · jessicamcinchak · Aug 12, 2021 · Aug 10, 2021 · Aug 10, 2021 · Aug 10, 2021
diff --git a/.env.example b/.env.example
@@ -1,2 +1,2 @@
-VITE_APP_ORDNANCE_SURVEY_KEY=👻
-VITE_APP_OS_WFS_KEY=👻
+VITE_APP_OS_VECTOR_TILES_API_KEY=👻
+VITE_APP_OS_FEATURES_API_KEY=👻
diff --git a/README.md b/README.md
@@ -8,9 +8,38 @@ An OpenLayers-powered Web Component map for tasks related to planning permission
 
 [CodeSandbox](https://codesandbox.io/s/confident-benz-rr0s9?file=/index.html)
 
-### Example: load static geojson
+#### Example: render the Ordnance Survey vector tile basemap
 
-Relevant configurable properties & their default values: 
+```html
+<my-map osVectorTilesApiKey="secret" />
+```
+
+Requires access to the Ordnance Survey Vector Tiles API. Sign up for a key here https://osdatahub.os.uk/plans.
+
+Available properties & their default values:
+```js
+@property({ type: Boolean })
+renderVectorTiles = true;
+
+@property({ type: String })
+osVectorTilesApiKey = "";
+```
+
+We want to use the most detailed base map possible, so `renderVectorTiles` is true by default. If it's true and you've provided an API key, we'll render the Ordnance Survey vector tiles. If you configure it to false, but still provide an API key, we'll render the OS raster base map. If there is no API key, regardless of the value of `renderVectorTiles`, we'll fallback to the OpenStreetMap tile server.
+
+#### Example: load static geojson
+
+```html
+<body>
+  <my-map geojsonBuffer="10" />
+  <script>
+    const map = document.querySelector("my-map");
+    map.geojsonData = { ... }
+  </script>
+</body>
+```
+
+Available properties & their default values:
 ```js
 @property({ type: Object })
 geojsonData = {
@@ -29,39 +58,42 @@ geojsonBuffer = 15;
 
 `geojsonColor` & `geojsonBuffer` are optional style properties. Color sets the stroke of the displayed data and buffer is used to fit the map view to the extent of the geojson features. `geojsonBuffer` corresponds to "value" param in OL documentation [here](https://openlayers.org/en/latest/apidoc/module-ol_extent.html).
 
-### Example: highlight features that intersect with a given coordinate
+#### Example: highlight features that intersect with a given coordinate
 
-Requires access to the Ordnance Survey Features API. Sign up for a key here: https://osdatahub.os.uk/plans. 
+```html
+<my-map showFeaturesAtPoint osFeaturesApiKey="secret" latitude="51.4858363" longitude="-0.0761246" featureColor="#8a2be2" />
+```
 
-Relevant configurable properties & their default values: 
+Requires access to the Ordnance Survey Features API. Sign up for a key here https://osdatahub.os.uk/plans. 
+
+Available properties & their default values:
 ```js
+@property({ type: Boolean })
+showFeaturesAtPoint = false;
+
+@property({ type: String })
+osFeaturesApiKey = "";
+
 @property({ type: Number })
 latitude = 51.507351;
 
 @property({ type: Number })
 longitude = -0.127758;
 
-@property({ type: Boolean })
-showFeaturesAtPoint = false;
-
 @property({ type: String })
 featureColor = "#0000ff";
 
 @property({ type: Number })
 featureBuffer = 40;
 ```
 
-Set `showFeaturesAtPoint` to true. `latitude` and `longitude` are required and used to query the OS Features API for features that contain this point.
+Set `showFeaturesAtPoint` to true. `osFeaturesApiKey`, `latitude`, and `longitude` are each required to query the OS Features API for features that contain this point.
 
 `featureColor` & `featureBuffer` are optional style properties. Color sets the stroke of the displayed data and buffer is used to fit the map view to the extent of the features. `featureBuffer` corresponds to "value" param in OL documentation [here](https://openlayers.org/en/latest/apidoc/module-ol_extent.html).
 
-```html
-<my-map latitude="51.4858363" longitude="-0.0761246" showFeaturesAtPoint featureColor="#8a2be2" />
-```
-
 ## Running Locally
 
-- Rename `.env.example` to `.env.local` and replace the values
+- Rename `.env.example` to `.env.development.local` and replace the values - or simply provide your API keys as props
 - Install dependencies `pnpm i`
 - Start dev server `pnpm dev`
 - Open http://localhost:3000
diff --git a/src/my-map.ts b/src/my-map.ts
@@ -10,9 +10,10 @@ import { Vector as VectorSource } from "ol/source";
 import { Stroke, Style } from "ol/style";
 import View from "ol/View";
 import { last } from "rambda";
+
 import { draw, drawingLayer, drawingSource, modify, snap } from "./draw";
-import { createFeatureLayer, featureSource, getFeatures } from "./os-features";
-import { osVectorTileBaseMap, rasterBaseMap } from "./os-layers";
+import { makeFeatureLayer, featureSource, getFeaturesAtPoint } from "./os-features";
+import { makeOsVectorTileBaseMap, makeRasterBaseMap } from "./os-layers";
 import { formatArea } from "./utils";
 
 @customElement("my-map")
@@ -84,17 +85,27 @@ export class MyMap extends LitElement {
   @property({ type: Number })
   geojsonBuffer = 12;
 
-  private useVectorTiles =
-    Boolean(import.meta.env.VITE_APP_ORDNANCE_SURVEY_KEY) &&
-    osVectorTileBaseMap;
+  @property({ type: Boolean })
+  renderVectorTiles = true;
+
+  @property({ type: String })
+  osVectorTilesApiKey = import.meta.env.VITE_APP_OS_VECTOR_TILES_API_KEY || "";
+
+  @property({ type: String })
+  osFeaturesApiKey = import.meta.env.VITE_APP_OS_FEATURES_API_KEY || "";
 
   // runs after the initial render
   firstUpdated() {
     const target = this.shadowRoot?.querySelector("#map") as HTMLElement;
 
+    const useVectorTiles = this.renderVectorTiles && Boolean(this.osVectorTilesApiKey);
+
+    const rasterBaseMap = makeRasterBaseMap(this.osVectorTilesApiKey);
+    const osVectorTileBaseMap = makeOsVectorTileBaseMap(this.osVectorTilesApiKey);
+
     const map = new Map({
       target,
-      layers: [this.useVectorTiles ? osVectorTileBaseMap : rasterBaseMap],
+      layers: [useVectorTiles ? osVectorTileBaseMap : rasterBaseMap],
       view: new View({
         projection: "EPSG:3857",
         extent: transformExtent(
@@ -179,7 +190,7 @@ export class MyMap extends LitElement {
 
       // log total area of feature (assumes geojson is a single polygon)
       const data = outlineSource.getFeatures()[0].getGeometry();
-      console.log('geojsonData total area:', formatArea(data));
+      console.log("geojsonData total area:", formatArea(data));
     }
 
     if (this.drawMode) {
@@ -213,9 +224,12 @@ export class MyMap extends LitElement {
     }
 
     if (this.showFeaturesAtPoint) {
-      getFeatures(fromLonLat([this.longitude, this.latitude]));
+      getFeaturesAtPoint(
+        fromLonLat([this.longitude, this.latitude]),
+        this.osFeaturesApiKey
+      );
 
-      const featureLayer = createFeatureLayer(this.featureColor);
+      const featureLayer = makeFeatureLayer(this.featureColor);
       map.addLayer(featureLayer);
 
       // ensure getFeatures has fetched successfully

diff --git a/src/os-features.ts b/src/os-features.ts
@@ -8,7 +8,7 @@ const featureServiceUrl = "https://api.os.uk/features/v1/wfs";
 
 export const featureSource = new VectorSource();
 
-export function createFeatureLayer(color: string) {
+export function makeFeatureLayer(color: string) {
   return new VectorLayer({
     source: featureSource,
     style: new Style({
@@ -24,8 +24,9 @@ export function createFeatureLayer(color: string) {
  * Create an OGC XML filter parameter value which will select the TopographicArea
  *   features containing the coordinates of the provided point
  * @param coord - xy coordinate
+ * @param apiKey - Ordnance Survey Features API key, sign up here: https://osdatahub.os.uk/plans
  */
-export function getFeatures(coord: Array<number>) {
+export function getFeaturesAtPoint(coord: Array<number>, apiKey: any) {
   const xml = `
     <ogc:Filter>
       <ogc:Contains>
@@ -38,9 +39,10 @@ export function getFeatures(coord: Array<number>) {
       </ogc:Contains>
     </ogc:Filter>
   `;
+
   // Define (WFS) parameters object
   const wfsParams = {
-    key: import.meta.env.VITE_APP_OS_WFS_KEY,
+    key: apiKey,
     service: "WFS",
     request: "GetFeature",
     version: "2.0.0",

diff --git a/src/os-layers.ts b/src/os-layers.ts
@@ -7,52 +7,47 @@ import { ATTRIBUTION } from "ol/source/OSM";
 import VectorTileSource from "ol/source/VectorTile";
 
 // Ordnance Survey sources
-const tileServiceUrl = `https://api.os.uk/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png?key=${
-  import.meta.env.VITE_APP_ORDNANCE_SURVEY_KEY
-}`;
-const vectorTileServiceUrl = `https://api.os.uk/maps/vector/v1/vts/tile/{z}/{y}/{x}.pbf?srs=3857&key=${
-  import.meta.env.VITE_APP_ORDNANCE_SURVEY_KEY
-}`;
-const vectorTileStyleUrl = `https://api.os.uk/maps/vector/v1/vts/resources/styles?srs=3857&key=${
-  import.meta.env.VITE_APP_ORDNANCE_SURVEY_KEY
-}`;
+const tileServiceUrl = `https://api.os.uk/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png?key=`;
+const vectorTileServiceUrl = `https://api.os.uk/maps/vector/v1/vts/tile/{z}/{y}/{x}.pbf?srs=3857&key=`;
+const vectorTileStyleUrl = `https://api.os.uk/maps/vector/v1/vts/resources/styles?srs=3857&key=`;
 
 // currently based on Southwark's OS license
 const COPYRIGHT = "© Crown copyright and database rights 2021 OS (0)100019252";
 
-export const rasterBaseMap = new TileLayer({
-  source: import.meta.env.VITE_APP_ORDNANCE_SURVEY_KEY
-    ? new XYZ({
-        url: tileServiceUrl,
-        attributions: [COPYRIGHT],
-        attributionsCollapsible: false,
-        maxZoom: 20,
-      })
-    : // No OrdnanceSurvey key found, sign up for free here https://osdatahub.os.uk/plans
-      new OSM({
-        attributions: [ATTRIBUTION],
-      }),
-});
-
-export const osVectorTileBaseMap = new VectorTileLayer({
-  declutter: true,
-  source: new VectorTileSource({
-    format: new MVT(),
-    url: vectorTileServiceUrl,
-    attributions: [COPYRIGHT],
-    attributionsCollapsible: false,
-  }),
-});
+export function makeRasterBaseMap(apiKey?: string) {
+  return new TileLayer({
+    source: apiKey
+      ? new XYZ({
+          url: tileServiceUrl + apiKey,
+          attributions: [COPYRIGHT],
+          attributionsCollapsible: false,
+          maxZoom: 20,
+        })
+      : // no OS API key found, sign up here https://osdatahub.os.uk/plans
+        new OSM({
+          attributions: [ATTRIBUTION],
+        }),
+  });
+}
 
-// ref https://github.com/openlayers/ol-mapbox-style#usage-example
-async function applyVectorTileStyle() {
-  try {
-    const response = await fetch(vectorTileStyleUrl);
-    const glStyle = await response.json();
-    stylefunction(osVectorTileBaseMap, glStyle, "esri");
-  } catch (error) {
-    console.log(error);
+export function makeOsVectorTileBaseMap(apiKey: string) {
+  let osVectorTileLayer = new VectorTileLayer({
+    declutter: true,
+    source: new VectorTileSource({
+      format: new MVT(),
+      url: vectorTileServiceUrl + apiKey,
+      attributions: [COPYRIGHT],
+      attributionsCollapsible: false,
+    }),
+  });
+
+  if (apiKey) {
+    // ref https://github.com/openlayers/ol-mapbox-style#usage-example
+    fetch(vectorTileStyleUrl + apiKey)
+      .then(response => response.json())
+      .then(glStyle => stylefunction(osVectorTileLayer, glStyle, "esri"))
+      .catch(error => console.log(error));
   }
-}
 
-applyVectorTileStyle();
+  return osVectorTileLayer;
+}
diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts
@@ -1,8 +1,8 @@
 /// <reference types="vite/client" />
 
 interface ImportMetaEnv {
-  VITE_APP_ORDNANCE_SURVEY_KEY: string;
-  VITE_APP_OS_WFS_KEY: string;
+  VITE_APP_OS_VECTOR_TILES_API_KEY: string;
+  VITE_APP_OS_FEATURES_API_KEY: string;
 }
 
 declare module "ol-mapbox-style/dist/stylefunction";