Optionally show or hide Bing 'placeholder' tiles

examples/bing-maps.html

@@ -3,7 +3,9 @@
 title: Bing Maps
 shortdesc: Example of a Bing Maps layer.
 docs: >
-  <p>When the Bing Maps tile service doesn't have tiles for a given resolution and region it returns "placeholder" tiles indicating that. Zoom the map beyond level 19 to see the "placeholder" tiles. If you want OpenLayers to display stretched tiles in place of "placeholder" tiles beyond zoom level 19 then set <code>maxZoom</code> to <code>19</code> in the options passed to <code>ol/source/BingMaps</code>.</p>
+  <p>When the Bing Maps tile service doesn't have tiles for a given resolution and region it returns "placeholder" tiles by default for `Aerial` and `OrdnanceSurvey' styles. If you want OpenLayers to display
+    stretched tiles in place of "placeholder" tiles at zoom levels where Bing Maps does not have tiles available then set
+    <code>placeholderTiles</code> to <code>false</code> in the options passed to <code>ol/source/BingMaps</code>.</p>
 tags: "bing, bing-maps"
 cloak:
   - key: AlEoTLTlzFB6Uf4Sy-ugXcRO21skQO7K8eObA5_L-8d20rjqZJLs2nkO1RMjGSPN

examples/bing-maps.js

@@ -20,9 +20,7 @@ for (i = 0, ii = styles.length; i < ii; ++i) {
       source: new BingMaps({
         key: 'AlEoTLTlzFB6Uf4Sy-ugXcRO21skQO7K8eObA5_L-8d20rjqZJLs2nkO1RMjGSPN',
         imagerySet: styles[i],
-        // use maxZoom 19 to see stretched tiles instead of the BingMaps
-        // "no photos at this zoom level" tiles
-        // maxZoom: 19
+        // placeholderTiles: false, // Optional. Prevents showing of BingMaps placeholder tiles
       }),
     })
   );

src/ol/source/BingMaps.js

@@ -68,6 +68,8 @@ const TOS_ATTRIBUTION =
  * @property {number|import("../array.js").NearestDirectionFunction} [zDirection=0]
  * Choose whether to use tiles with a higher or lower zoom level when between integer
  * zoom levels. See {@link module:ol/tilegrid/TileGrid~TileGrid#getZForResolution}.
+ * @property {boolean} placeholderTiles Whether to show BingMaps placeholder tiles when zoomed past the maximum level provided in an area. When `false`, requests beyond
+ * the maximum zoom level will return no tile. When `true`, the placeholder tile will be returned.
  */
 
 /**
@@ -164,6 +166,12 @@ class BingMaps extends TileImage {
      */
     this.imagerySet_ = options.imagerySet;
 
+    /**
+     * @private
+     * @type {boolean}
+     */
+    this.placeholderTiles_ = options.placeholderTiles;
+
     const url =
       'https://dev.virtualearth.net/REST/v1/Imagery/Metadata/' +
       this.imagerySet_ +
@@ -233,6 +241,7 @@ class BingMaps extends TileImage {
 
     const culture = this.culture_;
     const hidpi = this.hidpi_;
+    const placeholderTiles = this.placeholderTiles_;
     this.tileUrlFunction = createFromTileUrlFunctions(
       resource.imageUrlSubdomains.map(function (subdomain) {
         /** @type {import('../tilecoord.js').TileCoord} */
@@ -257,11 +266,20 @@ class BingMaps extends TileImage {
               tileCoord[2],
               quadKeyTileCoord
             );
-            let url = imageUrl;
+            const url = new URL(
+              imageUrl.replace('{quadkey}', quadKey(quadKeyTileCoord))
+            );
+            const params = url.searchParams;
             if (hidpi) {
-              url += '&dpi=d1&device=mobile';
+              params.set('dpi', 'd1');
+              params.set('device', 'mobile');
+            }
+            if (placeholderTiles === true) {
+              params.delete('n');
+            } else if (placeholderTiles === false) {
+              params.set('n', 'z');
             }
-            return url.replace('{quadkey}', quadKey(quadKeyTileCoord));
+            return url.toString();
           }
         );
       })

test/browser/spec/ol/source/BingMaps.test.js

@@ -29,6 +29,8 @@ describe('ol/source/BingMaps', function () {
       source = new BingMaps({
         imagerySet: 'AerialWithLabelsOnDemand',
         key: '',
+        placeholderTiles: false,
+        hidpi: true,
       });
 
       const client = new XMLHttpRequest();
@@ -102,6 +104,11 @@ describe('ol/source/BingMaps', function () {
         projection
       );
       expect(tileUrl.match(regex)[1]).to.equal(quadKey([6, 33, 22]));
+
+      const url = new URL(tileUrl);
+      expect(url.searchParams.get('dpi')).to.equal('d1');
+      expect(url.searchParams.get('device')).to.equal('mobile');
+      expect(url.searchParams.get('n')).to.equal('z');
     });
   });
 });