Add Place APIs

Package.swift

@@ -11,7 +11,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.23.0"),
-        .package(url: "https://github.com/vapor/jwt-kit.git", from: "5.0.0"),
+        .package(url: "https://github.com/vapor/jwt-kit.git", from: "5.0.1"),
     ],
     targets: [
         .target(

Sources/AppleMapsKit/AppleMapsClient.swift

@@ -391,7 +391,8 @@ public struct AppleMapsClient: Sendable {
             URLQueryItem(name: "origin", value: "\(origin.latitude),\(origin.longitude)"),
             URLQueryItem(
                 name: "destinations",
-                value: destinations.map { "\($0.latitude),\($0.longitude)" }.joined(separator: "|")),
+                value: destinations.map { "\($0.latitude),\($0.longitude)" }.joined(separator: "|")
+            ),
         ]
         if let transportType {
             queries.append(URLQueryItem(name: "transportType", value: transportType.rawValue))
@@ -465,6 +466,49 @@ public struct AppleMapsClient: Sendable {
         )
     }
 
+    /// Obtain a ``Place`` object for a given Place ID.
+    ///
+    /// - Parameters:
+    ///   - id: A single Place ID.
+    ///   - lang: The language code for the response.
+    ///
+    /// - Returns: A ``Place`` result.
+    public func place(id: String, lang: String? = nil) async throws -> Place {
+        var url = URL(string: "\(Self.apiServer)/v1/place/\(id)")!
+        if let lang {
+            url.append(queryItems: [URLQueryItem(name: "lang", value: lang)])
+        }
+        return try await decoder.decode(Place.self, from: httpGet(url: url))
+    }
+
+    /// Obtain a set of ``Place`` objects for a given set of Place IDs.
+    ///
+    /// - Parameters:
+    ///   - ids: A list of ``Place`` IDs.
+    ///   - lang: The language code for the response.
+    ///
+    /// - Returns: A list of ``PlacesResponse`` results.
+    public func places(ids: [String], lang: String? = nil) async throws -> PlacesResponse {
+        var url = URL(string: "\(Self.apiServer)/v1/place")!
+        var queries: [URLQueryItem] = [URLQueryItem(name: "ids", value: ids.joined(separator: ","))]
+        if let lang {
+            queries.append(URLQueryItem(name: "lang", value: lang))
+        }
+        url.append(queryItems: queries)
+        return try await decoder.decode(PlacesResponse.self, from: httpGet(url: url))
+    }
+
+    /// Get a list of alternate ``Place`` IDs given one or more Place IDs.
+    ///
+    /// - Parameter ids: A list of alternate ``Place`` IDs.
+    ///
+    /// - Returns: A list of ``AlternateIDsResponse`` results.
+    public func alternatePlaceIDs(ids: [String]) async throws -> AlternateIDsResponse {
+        var url = URL(string: "\(Self.apiServer)/v1/place/alternateIds")!
+        url.append(queryItems: [URLQueryItem(name: "ids", value: ids.joined(separator: ","))])
+        return try await decoder.decode(AlternateIDsResponse.self, from: httpGet(url: url))
+    }
+
     /// Makes an HTTP GET request.
     ///
     /// - Parameter url: URL for the request.

Sources/AppleMapsKit/DTOs/AlternateIDsResponse.swift

@@ -0,0 +1,19 @@
+/// A list of alternate Place IDs and associated errors.
+public struct AlternateIDsResponse: Codable, Sendable {
+    /// A list of ``PlacesResponse/PlaceLookupError`` results.
+    public let errors: [PlacesResponse.PlaceLookupError]?
+
+    /// A list of ``AlternateIDsResponse/AlternateIDs`` results.
+    public let results: [AlternateIDs]?
+}
+
+extension AlternateIDsResponse {
+    /// Contains a list of alternate ``Place`` IDs for a given Place ID.
+    public struct AlternateIDs: Codable, Sendable {
+        /// The ``Place`` ID.
+        public let id: String?
+
+        /// A list of alternate ``Place`` IDs for `id`.
+        public let alternateIds: [String]?
+    }
+}

Sources/AppleMapsKit/DTOs/PlacesResponse.swift

@@ -0,0 +1,19 @@
+/// A list of ``Place`` IDs and errors.
+public struct PlacesResponse: Codable, Sendable {
+    /// A list of ``PlacesResponse/PlaceLookupError`` results.
+    public let errors: [PlaceLookupError]?
+
+    /// A list of ``Place`` results.
+    public let places: [Place]?
+}
+
+extension PlacesResponse {
+    /// An error associated with a lookup call.
+    public struct PlaceLookupError: Codable, Sendable {
+        /// The ``Place`` ID.
+        public let id: String?
+
+        /// An error code that indicates whether an ``Place`` ID is invalid because it’s malformed, not found, or resulted in any other error.
+        public let errorCode: String?
+    }
+}

Tests/AppleMapsKitTests/AppleMapsKitTests.swift

@@ -188,4 +188,21 @@ struct AppleMapsKitTests {
         )
         #expect(!etas.isEmpty)
     }
+
+    @Test("Place") func place() async throws {
+        let place = try await client.place(id: "I7C250D2CDCB364A", lang: "en-US")
+        #expect(place != nil)
+    }
+
+    @Test("Places") func places() async throws {
+        let placesResponse = try await client.places(ids: ["ICFA2FAE5487B94AF", "IA6FD1E86A544F69D"], lang: "en-US")
+        let errors = try #require(placesResponse.errors)
+        #expect(!errors.isEmpty)
+    }
+
+    @Test("Alternate Place IDs") func alternatePlaceIDs() async throws {
+        let alternateIDsResponse = try await client.alternatePlaceIDs(ids: ["I7C250D2CDCB364A", "ICFA2FAE5487B94AF"])
+        let results = try #require(alternateIDsResponse.results)
+        #expect(!results.isEmpty)
+    }
 }