ガイド変更履歴HERE SDK API references
ガイド

地図の使用を開始する

HERE SDKは堅牢なマッピング機能を提供しているため、開発者はマップビューをアプリケーションに途切れることなく統合できます。主な機能には、マップ ビューの追加とカスタマイズ、表示される位置情報の調整、マップ プロパティの変更などがあります。地図検索 API の中心にあるのは、UIView のサブクラスである MapView であり、さまざまな設定可能なプロパティを持つ地図のベクトル ベースおよびラスター ベースの表現を提供します。

HERE Map Data は毎週更新され、常に利用可能な最新のマップ データを取得できるようになっています。マップビューを統合することで、このメリットを自動的に享受できます。

HERE SDK (Navigate) の場合、MapViewと衛星ベース以外のマップスキームは、Data IOとOCMベクタータイルの組み合わせに基づいています。これは、マップデータがキャッシュ、プリフェッチ、またはインストールされていない場合にオンラインで使用する場合に適用されます。データIOは、MapDownloaderまたはMapUpdaterを使用してオフラインマップをダウンロードまたは更新する際にもカウントされます。HERE SDK (Navigate) にのみ適用されます。

これらの機能の価格については、「HERE基本プランの価格表」を参照してください。価格についてご質問がある場合は、お問い合わせください

地図を表示する

マップビューを表示する前に、こちらに示すように、MapViewを統合する必要があります。StoryboardまたはSwiftUIを使用できます。

次のコードを追加して、normalDayマップレンダリングスタイルを表すマップスキームを使用してシーンを読み込みます。

mapView.mapScene.loadScene(mapScheme: MapScheme.normalDay, completion: onLoadScene)

完了ハンドラーとして、シーンの読み込みが成功したかどうかを通知するメソッドをオプションで実装できます。

// Completion handler when loading a map scene.
private func onLoadScene(mapError: MapError?) {
    guard mapError == nil else {
        print("Error: Map scene not loaded, \(String(describing: mapError))")
        return
    }

    // Configure the map.
    let camera = mapView.camera
    let distanceInMeters = MapMeasure(kind: .distanceInMeters, value: 1000 * 10)
    camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
                  zoom: distanceInMeters)
}

上記では、分離されたコードスニペットのみが表示されます。HERE SDKの統合と初期化を含む、簡単な地図アプリケーションの構築方法については、「利用開始」セクションを参照してください。

Screenshot: Showing a normal day map scheme.

埋め込みPOI (施設情報) を選択する

デフォルトでは、地図にはレストラン、公共交通機関、その他の名所のアイコンがいくつか表示されます。これらの施設情報 (POI) は Carto POI と呼ばれ、ユーザーが選択して詳細を取得できます。これらの埋め込み POI の表示を制御するオプションもあります。

埋め込み POI は、事前設定された Carto POI マーカーであり、デフォルトでは MapView に表示されます。MapMarker アイテムとは異なり、HERE Style Editor を使用せずにアイテムの内容や外観を変更することはできません。ただし、ユーザーはこれらのアイコンをタップして、場所、PlaceCategory、POI の名前を取得することはできます。

埋め込みPOIは、現在他のマップアイテムに隠れている場合を除き、他のMapMarkerアイテムと並行して選択できます。

// Conforming to TapDelegate protocol.
func onTap(origin: Point2D) {
    // You can also use a larger area to include multiple map icons.
    let rectangle2D = Rectangle2D(origin: origin,
                                  size: Size2D(width: 50, height: 50))
    // Creates a list of map content type from which the results will be picked.
    // The content type values can be mapContent, mapItems and customLayerData.
    var contentTypesToPickFrom = Array<MapScene.MapPickFilter.ContentType>();

    // mapContent is used when picking embedded Carto POIs, traffic incidents, vehicle restriction etc.
    // mapItems is used when picking map items such as MapMarker, MapPolyline, MapPolygon etc.
    // Currently we need Carto POIs so adding the mapContent filter.
    contentTypesToPickFrom.append(MapScene.MapPickFilter.ContentType.mapContent);
    var filter = MapScene.MapPickFilter(filter: contentTypesToPickFrom);
    mapView.pick(filter:filter,inside: rectangle2D, completion: onMapItemsPicked)
}

// Completion handler to receive picked map icons.
func onMapItemsPicked(mapPickResults: MapPickResult?) {
    guard let mapPickResults = mapPickResults else {
        print("Pick operation failed.")
        return
    }
    guard let pickedMapContent =  mapPickResults.mapContent else {
        print("Pick operation failed.")
        return
    }
    handlePickedCartoPOIs(pickedMapContent.pickedPlaces)
    handlePickedVehicleRestrictions(pickedMapContent.vehicleRestrictions)
    // ... handle also other map content types.
}
private func handlePickedCartoPOIs(_ cartoPOIList: [PickedPlace]) {
    if cartoPOIList.count == 0 {
        // No results found at pick location.
        return
    }

    let topmostCartoPOI = cartoPOIList.first!
    let name = topmostCartoPOI.name
    let lat = topmostCartoPOI.coordinates.latitude
    let lon = topmostCartoPOI.coordinates.longitude
    showDialog(title: "Carto POI picked",
               message: "Name: \(name). Location: \(lat), \(lon). See log for more place details.")

    // Now you can use the SearchEngine or the OfflineSearchEngine (if available for your license)
    // to retrieve the Place object containing more details.
}

あるいは、SearchEngineまたはOfflineSearchEngine (すべてのライセンスで使用できるわけではない) を使用して、さらなる詳細を含むPlaceオブジェクトを取得できます。PickMapContentResultを使用して、Placeの検索に使用できるPickedPlaceオブジェクトを取得します。

埋め込みの車両制限アイコンを選択する

MapFeatures.vehicleRestrictionsが有効で、車両制限アイコンを地図上にレンダリングできることを確認します。

1つまたは複数の車両制限アイコンが選択されると、選択された制限の詳細を取得するために、pickMapContentResult.vehicleRestrictionsを呼び出せるPickMapContentResultオブジェクトを含むMapPickResultを受け取ります。

このオブジェクトを使用して、ビットマップとしてアイコンにアクセスしたり、TruckTypeなどのその他の任意のプロパティを取得したりできます。

private func handlePickedVehicleRestrictions(_ vehicleRestrictions: [PickMapContentResult.VehicleRestrictionResult]) {
    if vehicleRestrictions.count == 0 {
        return
    }

    let topmostVehicleRestriction = vehicleRestrictions.first!

    createVehicleRestrictionIcon(vehicleRestrictionResult: topmostVehicleRestriction)
}

VehicleRestrictionResultでは、IconProviderを使用して、地図に表示される画像表現を生成できます。画像の生成にはiconProvider.createVehicleRestrictionIcon(..)を使用します。

このメソッドには次のパラメーターが必要です。

  • vehicleRestrictionResultPickMapContentResultからの車両制限オブジェクトの選択結果です。
  • currentMapSchemeMapViewの現在のマップスキームです。
  • IconProviderAssetType:UIまたは地図のアイコン最適化を指定します。
  • size:コールバックで生成される画像のサイズです。
  • iconProviderCallback:生成されたアイコンを受け取るコールバックオブジェクトです。

これには、次のコードを使用します。

private func createVehicleRestrictionIcon(vehicleRestrictionResult: PickMapContentResult.VehicleRestrictionResult){
    let iconProvider = IconProvider(self.mapView.mapContext)
    print("Mapview validity: \(self.mapView.isValid)")
    let iconCallback: IconProviderCallback = { icon, description, error in
        if let error = error {
            return
        }
        // Now you can make use of the bitmap representation.
    }
    let size = Size2D(width: 20.0, height: 20.0)

    iconProvider.createVehicleRestrictionIcon(pickingResult: vehicleRestrictionResult, mapScheme: currentMapScheme, assetType: IconProviderAssetType.ui, sizeConstraintsInPixels: size, completion: iconCallback)

}

GitHubの例については、「CartoPOIPicking」アプリを参照してください (Navigateにのみ関連します)。

埋め込みPOIの表示を制御する

地図上の埋め込みPOIの表示は、MapContentSettings.setPoiCategoriesVisibility(...)を使用して制御できます。これにより、POIカテゴリーのリストにVisibilityStateを設定できます (Navigateでのみ使用可能)。

// Note: You can change the visibility of individual embedded POI categories. This allows hiding specific categories of carto POIs.
var categoryIds: [String] = []
categoryIds.append(String(describing: PlaceCategory.eatAndDrinkRestaurant))
MapContentSettings.setPoiCategoriesVisibility(categoryIds: categoryIds, visibility: .hidden)

地図上の埋め込みPOIの表示/非表示は、Navigateでは制御できますが、Exploreでは制御できません。

すべてのPOIカテゴリーがすべてのマップスキームで使用できるわけではないことに注意してください。

サポートされているカテゴリーの一覧については、HERE Style Editorドキュメントを参照してください。

さらに、Exploreは埋め込みPOIとして表示されるすべてのPlaceCategoryフィールドをサポートしているわけではありません。たとえば、eatAndDrinkshoppingは、HERE SDK (Navigate) を使用している場合にのみ表示されます。

現在、以下の埋め込みPOIカテゴリーグループは、ExploreのMapViewには表示されません。

  • 宿泊施設
  • オートモーティブ
  • 飲食店
  • ショッピング

地図の言語を設定する

道路、都市、その他のマップ データのラベルを表示するために地図で使用する言語をカスタマイズできます。デフォルトでは、地域のローカル言語が使用されます。

MapView.primaryLanguage = languageCode を呼び出して世界の言語を設定するか、nil を設定してデフォルトの動作に戻します。これにより、MapView のすべてのインスタンスの言語が設定されます。特定の言語が世界の任意の地域でサポートされない場合は、代わりにその地域の現地言語で表示されます。

MapView.secondaryLanguage = languageCode を使用して、二重ラベルを表示できる場所に対応する第 2 地図言語を設定します。第 1 言語と第 2 言語のテキストが同じ場合は、第 1 言語のみが表示されます。リクエストされた言語がサポートされていない場合は、ローカル言語が使用されます。たとえば、インドのいくつかの都市では、ラテン語 (英語) とヒンディー語のテキストを使用する二重ラベルが同時に表示されます。

係争中の地域を処理する

HERE SDK は、複数の地理的・政治的な見解や紛争のある境界に対応し、国際的な見解 (デフォルト) またはローカル国の見解に基づいて地図の境界を表示します。ローカルな見解は、2つ以上の政治組織 (通常は国) が国境および所有権または支配権を主張する場合に、地図上の特定の領域にのみ影響を与えます。

デフォルトの地政学的見解を変更するには、SDKOptionsを使用してアクセスできるpoliticalViewメンバーに3文字の国コードを設定します。サポートされている国コードは、カバレージのページからアクセスできます。

国コードを設定すると、マップビューには設定されている国の地政学的見解に従ってすべての国の境界が表示され、MapViewにはそれに応じて国境が表示されます。

これはベータ機能としてリリースされていることに注意してください。

実行時に地政学的見解を変更する場合は、次のコード スニペットを使用します。

// Optionally, clear the cache, so that changing the options has an immediate effect.
SDKCache.fromEngine(SDKNativeEngine.sharedInstance!).clearCache { (error) in
    if error == nil {
        // ...
    }

    var options: SDKOptions? = SDKNativeEngine.sharedInstance?.options
    options?.politicalView = "ARG"

    // Now, initialize the HERE SDK again using the updated options.
}

これは、進行中の HERE SDK 操作中には呼び出さないようにしてください。新しいオプションを設定するには、新しい共有インスタンスも作成する必要があるためです。オプションと politicalView は、アプリケーションのライフサイクル中に HERE SDK を初めて初期化する前に 1 回のみ設定することが理想的です。

HERE ウォーターマークを管理する

HERE SDK を使用する場合は、常に HERE のロゴがマップ ビューに表示されている必要があります。デフォルトでは、HERE のロゴは地図の右下に配置されます。ただし、マップ ビュー インスタンスで setWatermarkLocation() を呼び出すことで、アプリのデザインに合わせて簡単にロゴの場所をカスタマイズできます。UI 要素が重なっているため必要であるという場合にのみ、デフォルトの配置を変更することをお勧めします。非常に小さいビューでは、地図の両端のサイズが 250 密度非依存ピクセル未満の場合、ウォーターマークが自動的に非表示になります。

HERE との特別な合意がある場合にのみ、HERE のロゴを削除できます。