Add Cesium ion geocoder to CesiumIonClient::Connection

CHANGES.md

@@ -2,7 +2,12 @@
 
 ### ? - ?
 
+##### Additions :tada:
+
+- Added `CesiumIonClient::Connection::geocode` method for making geocoding queries against the Cesium ion geocoder API.
+
 ##### Fixes :wrench:
+
 - Fixed a bug in `thenPassThrough` that caused a compiler error when given a value by r-value refrence.
 
 ### v0.42.0 - 2024-12-02

CesiumIonClient/CMakeLists.txt

@@ -40,6 +40,7 @@ target_link_libraries(CesiumIonClient
     PUBLIC
         CesiumAsync
         CesiumUtility
+        CesiumGeospatial
     PRIVATE
         picosha2::picosha2
         modp_b64::modp_b64

CesiumIonClient/include/CesiumIonClient/Connection.h

@@ -3,6 +3,7 @@
 #include "ApplicationData.h"
 #include "Assets.h"
 #include "Defaults.h"
+#include "Geocoder.h"
 #include "Profile.h"
 #include "Response.h"
 #include "Token.h"
@@ -291,6 +292,21 @@ class CESIUMASYNC_API Connection {
       const std::vector<std::string>& newScopes,
       const std::optional<std::vector<std::string>>& newAllowedUrls) const;
 
+  /**
+   * @brief Makes a request to the ion geocoding service.
+   *
+   * A geocoding service is used to make a plain text query (like an address,
+   * city name, or landmark) and obtain information about where it's located.
+   *
+   * @param provider The ion geocoding provider to use.
+   * @param type The type of request to make. See {@link GeocoderRequestType} for more information.
+   * @param query The query to make.
+   */
+  CesiumAsync::Future<Response<GeocoderResult>> geocode(
+      const GeocoderProviderType& provider,
+      const GeocoderRequestType& type,
+      const std::string& query);
+
   /**
    * @brief Decodes a token ID from a token.
    *

CesiumIonClient/include/CesiumIonClient/Geocoder.h

@@ -0,0 +1,131 @@
+#pragma once
+
+#include "CesiumGeospatial/Cartographic.h"
+#include "CesiumGeospatial/GlobeRectangle.h"
+
+#include <CesiumUtility/Math.h>
+
+#include <string>
+#include <variant>
+#include <vector>
+
+namespace CesiumIonClient {
+
+/**
+ * @brief The supported types of requests to geocoding API.
+ */
+enum GeocoderRequestType {
+  /**
+   * @brief Perform a full search from a complete query.
+   */
+  Search,
+
+  /**
+   * @brief Perform a quick search based on partial input, such as while a user
+   * is typing.
+   * The search results may be less accurate or exhaustive than using {@link GeocoderRequestType::Search}.
+   */
+  Autocomplete
+};
+
+/**
+ * @brief The supported providers that can be accessed through ion's geocoder
+ * API.
+ */
+enum GeocoderProviderType {
+  /**
+   * @brief Google geocoder, for use with Google data.
+   */
+  Google,
+
+  /**
+   * @brief Bing geocoder, for use with Bing data.
+   */
+  Bing,
+
+  /**
+   * @brief Use the default geocoder as set on the server. Used when neither
+   * Bing or Google data is used.
+   */
+  Default
+};
+
+/**
+ * @brief A single feature (a location or region) obtained from a geocoder
+ * service.
+ */
+struct GeocoderFeature {
+  /**
+   * @brief The user-friendly display name of this feature.
+   */
+  std::string displayName;
+
+  /**
+   * @brief The region on the globe for this feature.
+   */
+  std::variant<CesiumGeospatial::GlobeRectangle, CesiumGeospatial::Cartographic>
+      destination;
+
+  GeocoderFeature(
+      std::string& displayName_,
+      CesiumGeospatial::GlobeRectangle& destination_)
+      : displayName(displayName_), destination(destination_) {}
+  GeocoderFeature(
+      std::string& displayName_,
+      CesiumGeospatial::Cartographic& destination_)
+      : displayName(displayName_), destination(destination_) {}
+
+  /**
+   * @brief Returns a {@link CesiumGeospatial::GlobeRectangle} representing this feature.
+   *
+   * If the geocoder service returned a bounding box for this result, this will
+   * return the bounding box. If the geocoder service returned a coordinate for
+   * this result, this will return a zero-width rectangle at that coordinate.
+   */
+  CesiumGeospatial::GlobeRectangle getGlobeRectangle() const;
+
+  /**
+   * @brief Returns a {@link CesiumGeospatial::Cartographic} representing this feature.
+   *
+   * If the geocoder service returned a bounding box for this result, this will
+   * return the center of the bounding box. If the geocoder service returned a
+   * coordinate for this result, this will return the coordinate.
+   */
+  CesiumGeospatial::Cartographic getCartographic() const;
+};
+
+/**
+ * @brief Attribution information for a query to a geocoder service.
+ */
+struct GeocoderAttribution {
+  /**
+   * @brief An HTML string containing the necessary attribution information.
+   */
+  std::string html;
+
+  /**
+   * @brief If true, the credit should be visible in the main credit container.
+   * Otherwise, it can appear in a popover.
+   */
+  bool showOnScreen;
+
+  GeocoderAttribution(std::string& html_, bool showOnScreen_)
+      : html(html_), showOnScreen(showOnScreen_) {}
+};
+
+/**
+ * @brief The result of making a request to a geocoder service.
+ */
+struct GeocoderResult {
+  /**
+   * @brief Any necessary attributions for this geocoder result.
+   */
+  std::vector<GeocoderAttribution> attributions;
+
+  /**
+   * @brief The features obtained from this geocoder service, if any.
+   */
+  std::vector<GeocoderFeature> features;
+};
+
+}; // namespace CesiumIonClient

CesiumIonClient/src/Connection.cpp

@@ -1,10 +1,15 @@
 #include "CesiumIonClient/Connection.h"
 
+#include "CesiumGeospatial/BoundingRegion.h"
+#include "CesiumGeospatial/Cartographic.h"
+#include "CesiumGeospatial/GlobeRectangle.h"
+#include "CesiumIonClient/Geocoder.h"
 #include "fillWithRandomBytes.h"
 #include "parseLinkHeader.h"
 
 #include <CesiumAsync/IAssetResponse.h>
 #include <CesiumUtility/JsonHelpers.h>
+#include <CesiumUtility/Result.h>
 #include <CesiumUtility/SpanHelper.h>
 #include <CesiumUtility/Uri.h>
 #include <CesiumUtility/joinToString.h>
@@ -13,6 +18,7 @@
 #include <modp_b64.h>
 #include <rapidjson/document.h>
 #include <rapidjson/error/en.h>
+#include <rapidjson/pointer.h>
 #include <rapidjson/stringbuffer.h>
 #include <rapidjson/writer.h>
 #include <uriparser/Uri.h>
@@ -582,6 +588,85 @@ Defaults defaultsFromJson(const rapidjson::Document& json) {
   return defaults;
 }
 
+GeocoderResult geocoderResultFromJson(const rapidjson::Document& json) {
+  GeocoderResult result;
+
+  auto featuresMemberIt = json.FindMember("features");
+  if (featuresMemberIt != json.MemberEnd() &&
+      featuresMemberIt->value.IsArray()) {
+    auto featuresIt = featuresMemberIt->value.GetArray();
+    for (auto& feature : featuresIt) {
+      const rapidjson::Value* pLabel =
+          rapidjson::Pointer("/properties/label").Get(feature);
+      if (!pLabel) {
+        SPDLOG_WARN("Missing label for geocoder feature");
+        continue;
+      }
+
+      std::string label(pLabel->GetString());
+      auto bboxMemberIt = feature.FindMember("bbox");
+      if (bboxMemberIt == feature.MemberEnd() ||
+          !bboxMemberIt->value.IsArray()) {
+        // Could be a point value.
+        const rapidjson::Value* pCoordinates =
+            rapidjson::Pointer("/geometry/coordinates").Get(feature);
+        if (!pCoordinates) {
+          SPDLOG_WARN(
+              "Missing bbox and geometry.coordinates for geocoder feature");
+          continue;
+        }
+
+        if (!pCoordinates->IsArray() || pCoordinates->Size() != 2) {
+          SPDLOG_WARN("geometry.coordinates must be an array of size 2");
+          continue;
+        }
+
+        auto coordinatesArray = pCoordinates->GetArray();
+
+        CesiumGeospatial::Cartographic point =
+            CesiumGeospatial::Cartographic::fromDegrees(
+                JsonHelpers::getDoubleOrDefault(coordinatesArray[0], 0),
+                JsonHelpers::getDoubleOrDefault(coordinatesArray[1], 0));
+
+        result.features.emplace_back(label, point);
+      } else {
+        auto bboxIt = bboxMemberIt->value.GetArray();
+        if (bboxIt.Size() != 4) {
+          SPDLOG_WARN("bbox property should have exactly four values");
+          continue;
+        }
+
+        CesiumGeospatial::GlobeRectangle rect =
+            CesiumGeospatial::GlobeRectangle::fromDegrees(
+                JsonHelpers::getDoubleOrDefault(bboxIt[0], 0),
+                JsonHelpers::getDoubleOrDefault(bboxIt[1], 0),
+                JsonHelpers::getDoubleOrDefault(bboxIt[2], 0),
+                JsonHelpers::getDoubleOrDefault(bboxIt[3], 0));
+
+        result.features.emplace_back(label, rect);
+      }
+    }
+  }
+
+  auto attributionMemberIt = json.FindMember("attributions");
+  if (attributionMemberIt != json.MemberEnd() &&
+      attributionMemberIt->value.IsArray()) {
+    const auto& valueJson = attributionMemberIt->value;
+
+    result.attributions.reserve(valueJson.Size());
+
+    for (rapidjson::SizeType i = 0; i < valueJson.Size(); ++i) {
+      const auto& element = valueJson[i];
+      std::string html = JsonHelpers::getStringOrDefault(element, "html", "");
+      bool showOnScreen =
+          !JsonHelpers::getBoolOrDefault(element, "collapsible", false);
+      result.attributions.emplace_back(html, showOnScreen);
+    }
+  }
+
+  return result;
+}
+
 } // namespace
 
 Future<Response<Defaults>> Connection::defaults() const {
@@ -1179,3 +1264,64 @@ Connection::tokens(const std::string& url) const {
             return Response<TokenList>(pRequest, tokenListFromJson(d));
           });
 }
+
+CesiumAsync::Future<Response<GeocoderResult>> Connection::geocode(
+    const GeocoderProviderType& provider,
+    const GeocoderRequestType& type,
+    const std::string& query) {
+  const std::string endpointUrl = type == GeocoderRequestType::Autocomplete
+                                      ? "v1/geocode/autocomplete"
+                                      : "v1/geocode/search";
+  std::string requestUrl =
+      CesiumUtility::Uri::resolve(this->_apiUrl, endpointUrl);
+  requestUrl = CesiumUtility::Uri::addQuery(requestUrl, "text", query);
+
+  // Add provider type to url
+  switch (provider) {
+  case GeocoderProviderType::Bing:
+    requestUrl = CesiumUtility::Uri::addQuery(requestUrl, "geocoder", "BING");
+    break;
+  case GeocoderProviderType::Google:
+    requestUrl = CesiumUtility::Uri::addQuery(requestUrl, "geocoder", "GOOGLE");
+    break;
+  case GeocoderProviderType::Default:
+    requestUrl =
+        CesiumUtility::Uri::addQuery(requestUrl, "geocoder", "DEFAULT");
+    break;
+  }
+
+  return this->_pAssetAccessor
+      ->get(
+          this->_asyncSystem,
+          requestUrl,
+          {{"Accept", "application/json"},
+           {"Authorization", "Bearer " + this->_accessToken}})
+      .thenInMainThread(
+          [](std::shared_ptr<CesiumAsync::IAssetRequest>&& pRequest) {
+            const IAssetResponse* pResponse = pRequest->response();
+            if (!pResponse) {
+              return createEmptyResponse<GeocoderResult>();
+            }
+
+            if (pResponse->statusCode() < 200 ||
+                pResponse->statusCode() >= 300) {
+              return createErrorResponse<GeocoderResult>(pResponse);
+            }
+
+            rapidjson::Document d;
+            if (!parseJsonObject(pResponse, d)) {
+              return createJsonErrorResponse<GeocoderResult>(pResponse, d);
+            }
+            if (!d.IsObject()) {
+              return createJsonTypeResponse<GeocoderResult>(
+                  pResponse,
+                  "object");
+            }
+
+            return Response<GeocoderResult>(
+                geocoderResultFromJson(d),
+                pResponse->statusCode(),
+                std::string(),
+                std::string());
+          });
+}