Merge pull request #12299 from CesiumGS/choose-your-own-geocoder

Add option to select which geocoder is used

Author: ggetz

Apps/Sandcastle/gallery/3D Tiles Vertical Exaggeration.html

@@ -78,6 +78,7 @@ <h1>Loading...</h1>
           animation: false,
           sceneModePicker: false,
           baseLayerPicker: false,
+          geocoder: Cesium.IonGeocodeProviderType.GOOGLE,
           // The globe does not need to be displayed,
           // since the Photorealistic 3D Tiles include terrain
           globe: false,
@@ -104,7 +105,10 @@ <h1>Loading...</h1>
 
         // Add Photorealistic 3D Tiles
         try {
-          const tileset = await Cesium.createGooglePhotorealistic3DTileset();
+          const tileset = await Cesium.createGooglePhotorealistic3DTileset({
+            // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+            onlyUsingWithGoogleGeocoder: true,
+          });
           scene.primitives.add(tileset);
         } catch (error) {
           console.log(`Error loading Photorealistic 3D Tiles tileset.

Apps/Sandcastle/gallery/AEC Clipping.html

@@ -32,6 +32,7 @@
           animation: false,
           sceneModePicker: false,
           baseLayerPicker: false,
+          geocoder: Cesium.IonGeocodeProviderType.GOOGLE,
           // The globe does not need to be displayed,
           // since the Photorealistic 3D Tiles include terrain
           globe: false,
@@ -48,7 +49,10 @@
         // Add Photorealistic 3D Tiles
         let googleTileset;
         try {
-          googleTileset = await Cesium.createGooglePhotorealistic3DTileset();
+          googleTileset = await Cesium.createGooglePhotorealistic3DTileset({
+            // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+            onlyUsingWithGoogleGeocoder: true,
+          });
           viewer.scene.primitives.add(googleTileset);
         } catch (error) {
           console.log(`Error loading Photorealistic 3D Tiles tileset.

Apps/Sandcastle/gallery/Bing Maps Labels Only.html

@@ -67,6 +67,7 @@
           baseLayer: false,
           baseLayerPicker: false,
           infoBox: false,
+          geocoder: Cesium.IonGeocodeProviderType.BING,
         });
 
         const layers = viewer.imageryLayers;

Apps/Sandcastle/gallery/Clamp Entities to Ground.html

@@ -41,6 +41,7 @@
           timeline: false,
           animation: false,
           baseLayerPicker: false,
+          geocoder: Cesium.IonGeocodeProviderType.GOOGLE,
         });
         const scene = viewer.scene;
         scene.globe.depthTestAgainstTerrain = true;
@@ -56,7 +57,10 @@
 
         let worldTileset;
         try {
-          worldTileset = await Cesium.createGooglePhotorealistic3DTileset();
+          worldTileset = await Cesium.createGooglePhotorealistic3DTileset({
+            // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+            onlyUsingWithGoogleGeocoder: true,
+          });
           viewer.scene.primitives.add(worldTileset);
         } catch (error) {
           console.log(`Error loading Photorealistic 3D Tiles tileset.

Apps/Sandcastle/gallery/Clipping Regions.html

@@ -43,6 +43,7 @@
           animation: false,
           sceneModePicker: false,
           baseLayerPicker: false,
+          geocoder: Cesium.IonGeocoderProviderType.GOOGLE,
         });
         const scene = viewer.scene;
 
@@ -60,7 +61,10 @@
 
         let worldTileset;
         try {
-          worldTileset = await Cesium.createGooglePhotorealistic3DTileset();
+          worldTileset = await Cesium.createGooglePhotorealistic3DTileset({
+            // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+            onlyUsingWithGoogleGeocoder: true,
+          });
           scene.primitives.add(worldTileset);
         } catch (error) {
           console.log(`Error loading Photorealistic 3D Tiles tileset.

Apps/Sandcastle/gallery/Globe Interior.html

@@ -34,6 +34,7 @@
         //Sandcastle_Begin
         const viewer = new Cesium.Viewer("cesiumContainer", {
           orderIndependentTranslucency: false,
+          geocoder: Cesium.IonGeocodeProviderType.BING,
         });
 
         const scene = viewer.scene;

Apps/Sandcastle/gallery/Google Photorealistic 3D Tiles with Building Insert.html

@@ -32,6 +32,7 @@
           animation: false,
           sceneModePicker: false,
           baseLayerPicker: false,
+          geocoder: Cesium.IonGeocodeProviderType.GOOGLE,
           // The globe does not need to be displayed,
           // since the Photorealistic 3D Tiles include terrain
           globe: false,
@@ -42,7 +43,10 @@
 
         // Add Photorealistic 3D Tiles
         try {
-          const googleTileset = await Cesium.createGooglePhotorealistic3DTileset();
+          const googleTileset = await Cesium.createGooglePhotorealistic3DTileset({
+            // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+            onlyUsingWithGoogleGeocoder: true,
+          });
           viewer.scene.primitives.add(googleTileset);
         } catch (error) {
           console.log(`Error loading Photorealistic 3D Tiles tileset.

Apps/Sandcastle/gallery/Google Photorealistic 3D Tiles.html

@@ -32,6 +32,7 @@
           animation: false,
           sceneModePicker: false,
           baseLayerPicker: false,
+          geocoder: Cesium.IonGeocodeProviderType.GOOGLE,
           // The globe does not need to be displayed,
           // since the Photorealistic 3D Tiles include terrain
           globe: false,
@@ -42,7 +43,10 @@
 
         // Add Photorealistic 3D Tiles
         try {
-          const tileset = await Cesium.createGooglePhotorealistic3DTileset();
+          const tileset = await Cesium.createGooglePhotorealistic3DTileset({
+            // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+            onlyUsingWithGoogleGeocoder: true,
+          });
           viewer.scene.primitives.add(tileset);
         } catch (error) {
           console.log(`Error loading Photorealistic 3D Tiles tileset.

Apps/Sandcastle/gallery/Imagery Color To Alpha.html

@@ -51,7 +51,9 @@
       window.startup = async function (Cesium) {
         "use strict";
         //Sandcastle_Begin
-        const viewer = new Cesium.Viewer("cesiumContainer");
+        const viewer = new Cesium.Viewer("cesiumContainer", {
+          geocoder: Cesium.IonGeocodeProviderType.BING,
+        });
 
         const layers = viewer.scene.imageryLayers;
 

Apps/Sandcastle/gallery/Imagery Layers Manipulation.html

@@ -106,6 +106,7 @@
         //Sandcastle_Begin
         const viewer = new Cesium.Viewer("cesiumContainer", {
           baseLayerPicker: false,
+          geocoder: false,
         });
         const imageryLayers = viewer.imageryLayers;
 

Apps/Sandcastle/gallery/Imagery Layers Split.html

@@ -58,6 +58,7 @@
           ),
           baseLayerPicker: false,
           infoBox: false,
+          geocoder: false,
         });
 
         const layers = viewer.imageryLayers;

Apps/Sandcastle/gallery/development/3D Tiles Picking.html

@@ -34,6 +34,7 @@
           animation: false,
           baseLayerPicker: false,
           globe: false,
+          geocoder: false,
         });
         const scene = viewer.scene;
 
@@ -44,7 +45,10 @@
             onselect: async () => {
               scene.primitives.remove(tileset);
               try {
-                tileset = await Cesium.createGooglePhotorealistic3DTileset();
+                tileset = await Cesium.createGooglePhotorealistic3DTileset({
+                  // Only the Google Geocoder can be used with Google Photorealistic 3D Tiles.  Set the `geocode` property of the viewer constructor options to IonGeocodeProviderType.GOOGLE.
+                  onlyUsingWithGoogleGeocoder: true,
+                });
                 scene.primitives.add(tileset);
               } catch (error) {
                 console.log(error);

CHANGES.md

@@ -8,15 +8,24 @@
 
 - Added `getSample` to `SampledProperty` to get the time of samples. [#12253](https://github.com/CesiumGS/cesium/pull/12253)
 - Added `Entity.trackingReferenceFrame` property to allow tracking entities in their own inertial reference frame. [#12194](https://github.com/CesiumGS/cesium/pull/12194)
+- Added `GoogleGeocoderService` for standalone usage of Google geocoder. [#12299](https://github.com/CesiumGS/cesium/pull/12299)
 
 ##### Fixes :wrench:
 
 - Fix label rendering bug in WebGL1 contexts. [#12301](https://github.com/CesiumGS/cesium/pull/12301)
 - Updated WMS example URL in UrlTemplateImageryProvider documentation to use an active service. [#12323](https://github.com/CesiumGS/cesium/pull/12323)
 - Fix point cloud filtering performance on certain hardware [#12317](https://github.com/CesiumGS/cesium/pull/12317)
 
+##### Deprecated :hourglass_flowing_sand:
+
+- `createGooglePhotorealistic3DTileset(key)` has been deprecated. Use `createGooglePhotorealistic3DTileset({key})` instead. It will be removed in 1.126.
+
 #### @cesium/widgets
 
+##### Additions :tada:
+
+- Added the ability to choose between Bing and Google geocoders. Updated `Viewer` constructor to also accept `IonGeocoderProvider` [#12299](https://github.com/CesiumGS/cesium/pull/12299)
+
 ##### Fixes :wrench:
 
 - Added a `DeveloperError` when `globe` is set to `false` and a `baseLayer` is provided in `Viewer` options. This prevents errors caused by attempting to use a `baseLayer` without a globe. [#12274](https://github.com/CesiumGS/cesium/pull/12274)

packages/engine/Source/Core/BingMapsGeocoderService.js

@@ -10,6 +10,8 @@ const url = "https://dev.virtualearth.net/REST/v1/Locations";
 
 /**
  * Provides geocoding through Bing Maps.
+ *
+ * @see {@link https://www.microsoft.com/en-us/maps/bing-maps/product|Microsoft Bing Maps Platform APIs Terms Of Use}
  * @alias BingMapsGeocoderService
  * @constructor
  *

packages/engine/Source/Core/GoogleGeocoderService.js

@@ -0,0 +1,110 @@
+import Check from "./Check.js";
+import Credit from "./Credit.js";
+import defaultValue from "./defaultValue.js";
+import Rectangle from "./Rectangle.js";
+import Resource from "./Resource.js";
+import defined from "./defined.js";
+import DeveloperError from "./DeveloperError.js";
+import RuntimeError from "./RuntimeError.js";
+
+const API_URL = "https://maps.googleapis.com/maps/api/geocode/json";
+const CREDIT_HTML = `<img alt="Google" src="https://assets.ion.cesium.com/google-credit.png" style="vertical-align:-5px">`;
+
+/**
+ * Provides geocoding through Google.
+ *
+ * @see {@link https://developers.google.com/maps/documentation/geocoding/policies|Google Geocoding Policies}
+ * @alias GoogleGeocoderService
+ * @constructor
+ *
+ * @param {object} options Object with the following properties:
+ * @param {string} options.key An API key to use with the Google geocoding service
+ */
+function GoogleGeocoderService(options) {
+  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
+  const key = options.key;
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(key)) {
+    throw new DeveloperError("options.key is required.");
+  }
+  //>>includeEnd('debug');
+
+  this._resource = new Resource({
+    url: API_URL,
+    queryParameters: { key },
+  });
+
+  this._credit = new Credit(CREDIT_HTML, true);
+}
+
+Object.defineProperties(GoogleGeocoderService.prototype, {
+  /**
+   * Gets the credit to display after a geocode is performed. Typically this is used to credit
+   * the geocoder service.
+   * @memberof GoogleGeocoderService.prototype
+   * @type {Credit|undefined}
+   * @readonly
+   */
+  credit: {
+    get: function () {
+      return this._credit;
+    },
+  },
+});
+
+/**
+ * Get a list of possible locations that match a search string.
+ *
+ * @function
+ *
+ * @param {string} query The query to be sent to the geocoder service
+ * @returns {Promise<GeocoderService.Result[]>}
+ * @throws {RuntimeError} If the services returns a status other than <code>OK</code> or <code>ZERO_RESULTS</code>
+ */
+GoogleGeocoderService.prototype.geocode = async function (query) {
+  // See API documentation at https://developers.google.com/maps/documentation/geocoding/requests-geocoding
+
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.string("query", query);
+  //>>includeEnd('debug');
+
+  const resource = this._resource.getDerivedResource({
+    queryParameters: {
+      address: query,
+    },
+  });
+
+  const response = await resource.fetchJson();
+
+  if (response.status === "ZERO_RESULTS") {
+    return [];
+  }
+
+  if (response.status !== "OK") {
+    throw new RuntimeError(
+      `GoogleGeocoderService got a bad response ${response.status}: ${response.error_message}`,
+    );
+  }
+
+  const results = response.results.map((result) => {
+    const southWest = result.geometry.viewport.southwest;
+    const northEast = result.geometry.viewport.northeast;
+    return {
+      displayName: result.formatted_address,
+      destination: Rectangle.fromDegrees(
+        southWest.lng,
+        southWest.lat,
+        northEast.lng,
+        northEast.lat,
+      ),
+      attribution: {
+        html: CREDIT_HTML,
+        collapsible: false,
+      },
+    };
+  });
+
+  return results;
+};
+
+export default GoogleGeocoderService;

packages/engine/Source/Core/IonGeocodeProviderType.js

@@ -0,0 +1,33 @@
+/**
+ * Underlying geocoding services that can be used via Cesium ion.
+ *
+ * @enum {string}
+ */
+const IonGeocodeProviderType = {
+  /**
+   * Google geocoder, for use with Google data.
+   *
+   * @type {string}
+   * @constant
+   */
+  GOOGLE: "GOOGLE",
+
+  /**
+   * Bing geocoder, for use with Bing data.
+   *
+   * @type {string}
+   * @constant
+   */
+  BING: "BING",
+
+  /**
+   * Use the default geocoder as set on the server.  Used when neither Bing or
+   * Google data is used.
+   *
+   * @type {string}
+   * @constant
+   */
+  DEFAULT: "DEFAULT",
+};
+
+export default Object.freeze(IonGeocodeProviderType);