Add Detail API lookup by Mapbox ID

CHANGELOG.md

@@ -6,6 +6,8 @@ Guide: https://keepachangelog.com/en/1.0.0/
 
 ## Unreleased
 
+- [Details] Add `SearchEngine.retrieve(mapboxID: String, options: DetailsOptions)` function.
+
 ## 2.7.1
 
 - [Core] Update dependencies.

MapboxSearch.xcodeproj/project.pbxproj

@@ -13,6 +13,10 @@
 		042477C52B72CCB000D870D5 /* geocoding-reverse-geocoding.json in Resources */ = {isa = PBXBuildFile; fileRef = 042477C42B72CCB000D870D5 /* geocoding-reverse-geocoding.json */; };
 		042477C62B72CCB000D870D5 /* geocoding-reverse-geocoding.json in Resources */ = {isa = PBXBuildFile; fileRef = 042477C42B72CCB000D870D5 /* geocoding-reverse-geocoding.json */; };
 		042477C72B72CCB000D870D5 /* geocoding-reverse-geocoding.json in Resources */ = {isa = PBXBuildFile; fileRef = 042477C42B72CCB000D870D5 /* geocoding-reverse-geocoding.json */; };
+		0427854F2C77899700A0934D /* search-box-retrieve-mapbox-id.json in Resources */ = {isa = PBXBuildFile; fileRef = 0427854E2C77899700A0934D /* search-box-retrieve-mapbox-id.json */; };
+		042785502C77899700A0934D /* search-box-retrieve-mapbox-id.json in Resources */ = {isa = PBXBuildFile; fileRef = 0427854E2C77899700A0934D /* search-box-retrieve-mapbox-id.json */; };
+		042785512C77899700A0934D /* search-box-retrieve-mapbox-id.json in Resources */ = {isa = PBXBuildFile; fileRef = 0427854E2C77899700A0934D /* search-box-retrieve-mapbox-id.json */; };
+		042785582C79008300A0934D /* SearchEngineTests+Details.swift in Sources */ = {isa = PBXBuildFile; fileRef = 042785572C79008300A0934D /* SearchEngineTests+Details.swift */; };
 		042BEB172C2DDFAA0004CD7B /* MapboxCommon in Frameworks */ = {isa = PBXBuildFile; productRef = 042BEB162C2DDFAA0004CD7B /* MapboxCommon */; };
 		042BEB1A2C2DE30E0004CD7B /* MapboxMaps in Frameworks */ = {isa = PBXBuildFile; productRef = 042BEB192C2DE30E0004CD7B /* MapboxMaps */; };
 		043339CD2C61295D001650FA /* Atlantis in Frameworks */ = {isa = PBXBuildFile; productRef = 043339CC2C61295D001650FA /* Atlantis */; };
@@ -51,6 +55,7 @@
 		04970F8D2B7A97C900213763 /* PrivacyInfo.xcprivacy in Resources */ = {isa = PBXBuildFile; fileRef = 04970F8C2B7A97C900213763 /* PrivacyInfo.xcprivacy */; };
 		0498A7442CB486AE008F8903 /* ForwardExampleViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0498A7422CB48683008F8903 /* ForwardExampleViewController.swift */; };
 		049FE3A82C6A50BB00F54FB2 /* RetrieveOptions.swift in Sources */ = {isa = PBXBuildFile; fileRef = 049FE3A72C6A50BB00F54FB2 /* RetrieveOptions.swift */; };
+		04A26C652C7535BD00443527 /* DetailsOptions.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04A26C642C7535BD00443527 /* DetailsOptions.swift */; };
 		04A972CC2C938B8800C5F1A8 /* UserRecordsLayerTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 04A972C62C923C5300C5F1A8 /* UserRecordsLayerTests.swift */; };
 		04AB0B4B2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json in Resources */ = {isa = PBXBuildFile; fileRef = 04AB0B4A2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json */; };
 		04AB0B4C2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json in Resources */ = {isa = PBXBuildFile; fileRef = 04AB0B4A2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json */; };
@@ -558,6 +563,8 @@
 		0405809C2BA8E67D00A54CB9 /* OwningObjectDeallocatedErrorTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OwningObjectDeallocatedErrorTests.swift; sourceTree = "<group>"; };
 		042477C12B7290E700D870D5 /* SearchEngineGeocodingIntegrationTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SearchEngineGeocodingIntegrationTests.swift; sourceTree = "<group>"; };
 		042477C42B72CCB000D870D5 /* geocoding-reverse-geocoding.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = "geocoding-reverse-geocoding.json"; sourceTree = "<group>"; };
+		0427854E2C77899700A0934D /* search-box-retrieve-mapbox-id.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; path = "search-box-retrieve-mapbox-id.json"; sourceTree = "<group>"; };
+		042785572C79008300A0934D /* SearchEngineTests+Details.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "SearchEngineTests+Details.swift"; sourceTree = "<group>"; };
 		04340D1F2C6BD06500B4F242 /* ResultChildMetadata.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ResultChildMetadata.swift; sourceTree = "<group>"; };
 		043A3D4C2B30F38300DB681B /* CoreAddress+AddressComponents.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "CoreAddress+AddressComponents.swift"; sourceTree = "<group>"; };
 		044A6B722BA8933200A9F2A2 /* PreviewCategoriesFavoritesSegmentControl.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PreviewCategoriesFavoritesSegmentControl.swift; sourceTree = "<group>"; };
@@ -578,6 +585,7 @@
 		04970F8C2B7A97C900213763 /* PrivacyInfo.xcprivacy */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.xml; path = PrivacyInfo.xcprivacy; sourceTree = "<group>"; };
 		0498A7422CB48683008F8903 /* ForwardExampleViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ForwardExampleViewController.swift; sourceTree = "<group>"; };
 		049FE3A72C6A50BB00F54FB2 /* RetrieveOptions.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = RetrieveOptions.swift; sourceTree = "<group>"; };
+		04A26C642C7535BD00443527 /* DetailsOptions.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DetailsOptions.swift; sourceTree = "<group>"; };
 		04A972C62C923C5300C5F1A8 /* UserRecordsLayerTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UserRecordsLayerTests.swift; sourceTree = "<group>"; };
 		04AB0B4A2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json */ = {isa = PBXFileReference; lastKnownFileType = text.json; path = mapbox.places.san.francisco.json; sourceTree = "<group>"; };
 		04AB0B792B6AF37800FDE7D5 /* DiscoverIntegrationTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DiscoverIntegrationTests.swift; sourceTree = "<group>"; };
@@ -1048,6 +1056,14 @@
 			path = autofill;
 			sourceTree = "<group>";
 		};
+		042785562C79006E00A0934D /* Details */ = {
+			isa = PBXGroup;
+			children = (
+				042785572C79008300A0934D /* SearchEngineTests+Details.swift */,
+			);
+			path = Details;
+			sourceTree = "<group>";
+		};
 		046818D22B87F2810082B188 /* search-box */ = {
 			isa = PBXGroup;
 			children = (
@@ -1071,6 +1087,7 @@
 		046818D62B87FA450082B188 /* search-box */ = {
 			isa = PBXGroup;
 			children = (
+				0427854E2C77899700A0934D /* search-box-retrieve-mapbox-id.json */,
 				04DFB41B2B8CFEC100231830 /* search-box-retrieve-san-francisco.json */,
 				046818DA2B87FAB20082B188 /* search-box-category.json */,
 				046818E02B87FF5C0082B188 /* search-box-suggestions-minsk.json */,
@@ -1115,6 +1132,15 @@
 			path = Resources;
 			sourceTree = "<group>";
 		};
+		04A26C632C75359B00443527 /* SearchRequest */ = {
+			isa = PBXGroup;
+			children = (
+				049FE3A72C6A50BB00F54FB2 /* RetrieveOptions.swift */,
+				04A26C642C7535BD00443527 /* DetailsOptions.swift */,
+			);
+			path = SearchRequest;
+			sourceTree = "<group>";
+		};
 		0498A7412CB4866E008F8903 /* Forward */ = {
 			isa = PBXGroup;
 			children = (
@@ -1288,6 +1314,7 @@
 		141789F0287C30450000AE79 /* Use Cases */ = {
 			isa = PBXGroup;
 			children = (
+				042785562C79006E00A0934D /* Details */,
 				14FA6577295347E700056E5B /* Place Autocomplete */,
 				14FA6576295347CB00056E5B /* Address Autofill */,
 			);
@@ -1641,9 +1668,9 @@
 				FEEDD2E32508DFE400DC0A98 /* AbstractSearchEngine.swift */,
 				04C127542B62F6BC00884325 /* ApiType.swift */,
 				FEEDD2D82508DFE400DC0A98 /* SearchEngine.swift */,
-				049FE3A72C6A50BB00F54FB2 /* RetrieveOptions.swift */,
 				FEEDD2EB2508DFE400DC0A98 /* CategorySearchEngine.swift */,
 				04C0848C2B4C82F3002F9C69 /* SdkInformation.swift */,
+				04A26C632C75359B00443527 /* SearchRequest */,
 			);
 			path = Engine;
 			sourceTree = "<group>";
@@ -2345,6 +2372,7 @@
 				F9B62CCB264BCC2600492999 /* suggestions-empty.json in Resources */,
 				048823492B6B0A9D00C770AA /* category-hotel-search-along-route-jp.json in Resources */,
 				04AB0B4C2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json in Resources */,
+				042785502C77899700A0934D /* search-box-retrieve-mapbox-id.json in Resources */,
 				04DFB4112B8CF46D00231830 /* search-box-retrieve-categories.json in Resources */,
 				04DFB4212B8D0ABE00231830 /* search-box-retrieve-recursion.json in Resources */,
 				046818DC2B87FAB20082B188 /* search-box-category.json in Resources */,
@@ -2381,6 +2409,7 @@
 				04DFB4162B8CFD4700231830 /* search-box-suggestions-san-francisco.json in Resources */,
 				F94FFA4826453D410019ED9B /* reverse-geocoding-sbs.json in Resources */,
 				04DFB4222B8D0ABE00231830 /* search-box-retrieve-recursion.json in Resources */,
+				042785512C77899700A0934D /* search-box-retrieve-mapbox-id.json in Resources */,
 				046818E32B87FF5C0082B188 /* search-box-suggestions-minsk.json in Resources */,
 				2CD8AC4B29F1D38800C47BE4 /* suggestions-with-mixed-coordinates.json in Resources */,
 				0477904B2B890A8500A99528 /* search-box-recursion.json in Resources */,
@@ -2415,6 +2444,7 @@
 				F9C557A52670CB0400BE8B94 /* suggestions-empty.json in Resources */,
 				048823482B6B0A9D00C770AA /* category-hotel-search-along-route-jp.json in Resources */,
 				04AB0B4B2B6AADB700FDE7D5 /* mapbox.places.san.francisco.json in Resources */,
+				0427854F2C77899700A0934D /* search-box-retrieve-mapbox-id.json in Resources */,
 				04DFB4102B8CF46D00231830 /* search-box-retrieve-categories.json in Resources */,
 				04DFB4202B8D0ABE00231830 /* search-box-retrieve-recursion.json in Resources */,
 				046818DB2B87FAB20082B188 /* search-box-category.json in Resources */,
@@ -2686,6 +2716,7 @@
 				F914EE642743E4F400D4F173 /* CoreAliases.swift in Sources */,
 				F998AED825D17DFF00230F34 /* SearchResponseInfo.swift in Sources */,
 				FEEDD3082508DFE400DC0A98 /* HistoryRecord.swift in Sources */,
+				04A26C652C7535BD00443527 /* DetailsOptions.swift in Sources */,
 				FEEDD3032508DFE400DC0A98 /* SearchRequestOptions.swift in Sources */,
 				FEEDD2F82508DFE400DC0A98 /* RecordsProviderInteractorNativeCore.swift in Sources */,
 				F97E9A84268C7BBE00F6353D /* DefaultStringInterpolation+Extensions.swift in Sources */,
@@ -2823,6 +2854,7 @@
 				FE489B1B2566D839002BF730 /* SearchNavigationProfileTests.swift in Sources */,
 				F9ACA6152642BEE100F50CD4 /* MockResponse.swift in Sources */,
 				F9ACA6142642BEDD00F50CD4 /* MockWebServer.swift in Sources */,
+				042785582C79008300A0934D /* SearchEngineTests+Details.swift in Sources */,
 				FE8F8215256D46F400A100D4 /* SearchResultMetadata+Samples.swift in Sources */,
 				FECB50E3255410BC0026302E /* CLLocationCoordinate2D+Samples.swift in Sources */,
 				14173C3A28784ABC00B20E1C /* NonEmptyArray+Tests.swift in Sources */,

Sources/Demo/ResultDetailViewController.swift

@@ -37,7 +37,8 @@ class ResultDetailViewController: UIViewController {
         feedbackButton.addTarget(self, action: #selector(showFeedbackAlert), for: .touchUpInside)
     }
 
-    @objc func showFeedbackAlert() {
+    @objc
+    func showFeedbackAlert() {
         let alert = UIAlertController(
             title: "Submit Feedback?",
             message: nil,

Sources/Demo/UIComponents/PointAnnotation+Search.swift

@@ -4,11 +4,11 @@ import UIKit
 
 extension PointAnnotation {
     static func pointAnnotation(_ searchResult: SearchResult) -> Self {
-        Self.pointAnnotation(coordinate: searchResult.coordinate, name: searchResult.name)
+        pointAnnotation(coordinate: searchResult.coordinate, name: searchResult.name)
     }
 
     static func pointAnnotation(_ searchResult: AddressAutofill.Result) -> Self {
-        Self.pointAnnotation(coordinate: searchResult.coordinate, name: searchResult.name)
+        pointAnnotation(coordinate: searchResult.coordinate, name: searchResult.name)
     }
 
     static func pointAnnotation(_ searchResult: PlaceAutocomplete.Result) -> Self? {

Sources/MapboxSearch/InternalAPI/CoreAliases.swift

@@ -11,6 +11,7 @@ typealias CoreBoundingBox = MapboxCoreSearch.LonLatBBox
 typealias CoreSearchResult = MapboxCoreSearch.SearchResult
 typealias CoreAttributeSet = MapboxCoreSearch.AttributeSet
 typealias CoreRetrieveOptions = MapboxCoreSearch.RetrieveOptions
+typealias CoreDetailsOptions = MapboxCoreSearch.DetailsOptions
 typealias CoreRoutablePoint = MapboxCoreSearch.RoutablePoint
 typealias CoreResultMetadata = MapboxCoreSearch.ResultMetadata
 typealias CoreRequestOptions = MapboxCoreSearch.RequestOptions

Sources/MapboxSearch/InternalAPI/CoreSearchEngineProtocol.swift

@@ -1,6 +1,8 @@
 import CoreLocation
 import Foundation
 
+typealias CoreSearchResponseCompletion = (CoreSearchResponseProtocol?) -> Void
+
 protocol CoreSearchEngineProtocol {
     /**
      -------------------------------------------------------------------------------------------
@@ -79,12 +81,11 @@ protocol CoreSearchEngineProtocol {
         completion: @escaping (CoreSearchResponseProtocol?) -> Void
     )
 
-    @discardableResult
     func forward(
         query: String,
         options: CoreSearchOptions,
         completion: @escaping (CoreSearchResponseProtocol?) -> Void
-    ) -> UInt64
+    )
 
     func setTileStore(_ tileStore: MapboxCommon.TileStore, completion: (() -> Void)?)
 
@@ -95,6 +96,12 @@ protocol CoreSearchEngineProtocol {
     func addOfflineIndexObserver(for observer: CoreOfflineIndexObserver)
 
     func removeOfflineIndexObserver(for observer: CoreOfflineIndexObserver)
+
+    func retrieveDetails(
+        for mapboxId: String,
+        options: CoreDetailsOptions,
+        completion: @escaping CoreSearchResponseCompletion
+    )
 }
 
 extension CoreSearchEngine: CoreSearchEngineProtocol {
@@ -273,12 +280,23 @@ extension CoreSearchEngine: CoreSearchEngineProtocol {
         })
     }
 
-    @discardableResult
+    func retrieveDetails(
+        for mapboxId: String,
+        options: CoreDetailsOptions,
+        completion: @escaping CoreSearchResponseCompletion
+    ) {
+        retrieveDetails(forMapboxId: mapboxId, options: options) { response in
+            DispatchQueue.main.async {
+                completion(response)
+            }
+        }
+    }
+
     func forward(
         query: String,
         options: CoreSearchOptions,
         completion: @escaping (CoreSearchResponseProtocol?) -> Void
-    ) -> UInt64 {
+    ) {
         forward(forQuery: query, options: options, callback: { response in
             DispatchQueue.main.async {
                 completion(response)

Sources/MapboxSearch/InternalAPI/Telemetry/EventsServiceProtocol.swift

@@ -5,4 +5,4 @@ protocol EventsServiceProtocol {
     func sendEvent(for event: Event, callback: EventsServiceResponseCallback?)
 }
 
-extension EventsService: EventsServiceProtocol { }
+extension EventsService: EventsServiceProtocol {}

Sources/MapboxSearch/PublicAPI/DefaultLocationProvider.swift

@@ -109,7 +109,7 @@ extension DefaultLocationProvider: LocationProvider {
 }
 
 private class DefaultLocationManagerDelegate: NSObject, CLLocationManagerDelegate {
-    unowned var locationProvider: DefaultLocationProvider
+    unowned(unsafe) var locationProvider: DefaultLocationProvider
 
     init(unownedLocationProvider: DefaultLocationProvider) {
         self.locationProvider = unownedLocationProvider

Sources/MapboxSearch/PublicAPI/Engine/SearchEngine.swift

@@ -209,6 +209,8 @@ public class SearchEngine: AbstractSearchEngine {
         offlineMode == .disabled ? engine.reverseGeocoding : engine.reverseGeocodingOffline
     }
 
+    /// Concrete implementation for a typical ``select(suggestions:)`` invocation. Performs the work of a Mapbox API
+    /// retrieve/ endpoint request.
     func retrieve(
         suggestion: SearchSuggestion,
         retrieveOptions: RetrieveOptions?
@@ -336,6 +338,37 @@ public class SearchEngine: AbstractSearchEngine {
         }
     }
 
+    /// Process a single response from ``retrieve(mapboxID:options:)``
+    /// - Parameters:
+    ///   - coreResponse: The API response
+    ///   - mapboxID: The ID used to create the original request.
+    private func processDetailsResponse(_ coreResponse: CoreSearchResponseProtocol?, mapboxID: String) {
+        assert(offlineMode == .disabled)
+        guard let response = preProcessResponse(coreResponse) else {
+            return
+        }
+
+        switch response.process() {
+        case .success(let responseResult):
+            // Response Info is not supported for retrieving by Details API at this time.
+            responseInfo = nil
+
+            guard let result = responseResult.results.first else {
+                let errorMessage = "Could not retrieve details result."
+                delegate?.searchErrorHappened(
+                    searchError: .internalSearchRequestError(message: errorMessage),
+                    searchEngine: self
+                )
+                return
+            }
+            delegate?.resultResolved(result: result, searchEngine: self)
+
+        case .failure(let searchError):
+            eventsManager.reportError(searchError)
+            delegate?.searchErrorHappened(searchError: searchError, searchEngine: self)
+        }
+    }
+
     private func resolveServerRetrieveResponse(_ coreResponse: CoreSearchResponseProtocol?) -> SearchResult? {
         guard let response = preProcessRetrieveResponse(coreResponse) else {
             return nil
@@ -576,6 +609,27 @@ extension SearchEngine {
     }
 }
 
+// MARK: - Public Details API
+
+extension SearchEngine {
+    /// Retrieve a POI by its Mapbox ID.
+    /// When you already have a Mapbox ID, you can retrieve the associated POI data directly rather than using
+    /// ``search(query:options:)`` and ``select(suggestions:)``
+    /// For example, to refresh the data for  a _cached POI_ , simply query ``retrieve(mapboxID:options:)``, instead of
+    /// using new `search` and `select` invocations.
+    /// - Parameters:
+    ///   - mapboxID: The Mapbox ID for a known POI. Mapbox IDs will be returned in Search responses and may be cached.
+    ///   - detailsOptions: Options to configure this query. May be nil.
+    public func retrieve(mapboxID: String, options detailsOptions: DetailsOptions = DetailsOptions()) {
+        assert(offlineMode == .disabled)
+
+        let detailsOptions = detailsOptions
+        engine.retrieveDetails(for: mapboxID, options: detailsOptions.toCore()) { [weak self] serverResponse in
+            self?.processDetailsResponse(serverResponse, mapboxID: mapboxID)
+        }
+    }
+}
+
 // MARK: - IndexableDataResolver
 
 extension SearchEngine: IndexableDataResolver {

Sources/MapboxSearch/PublicAPI/Engine/SearchRequest/DetailsOptions.swift

@@ -0,0 +1,37 @@
+// Copyright © 2024 Mapbox. All rights reserved.
+
+import Foundation
+
+/// Options to configure a request for ``SearchEngine/retrieve(mapboxID:options:)``
+public struct DetailsOptions: Sendable {
+    /// Besides the basic metadata attributes, developers can request additional
+    /// attributes by setting attribute_sets parameter with attribute set values,
+    /// for example &attribute_sets=basic,photos,visit.
+    /// The requested metadata will be provided in metadata object in the response.
+    public var attributeSets: [AttributeSet]
+
+    /// The ISO language code to be returned. If not provided, the default is English.
+    public var language: String?
+
+    /// The two digit ISO country code (such as 'JP') to request a worldview for the location data, if applicable data
+    /// is available.
+    /// This parameters will only be applicable for Boundaries and Places feature types.
+    public var worldview: String?
+
+    public init(attributeSets: [AttributeSet]? = nil, language: String? = nil, worldview: String? = nil) {
+        // Always make sure that the basic attribute set is present
+        var attributeSets: Set<AttributeSet> = Set(attributeSets ?? [.basic])
+        attributeSets.insert(.basic)
+        self.attributeSets = Array(attributeSets)
+        self.language = language
+        self.worldview = worldview
+    }
+
+    func toCore() -> CoreDetailsOptions {
+        CoreDetailsOptions(
+            attributeSets: attributeSets.map { NSNumber(value: $0.coreValue.rawValue) },
+            language: language,
+            worldview: worldview
+        )
+    }
+}