iOS 開発者ガイド for SDK

検索と発見

SDK for iOS には Places API が含まれており、実世界の場所についての検索、発見、詳細情報の取得を行う機能を提供します。

HERE Places では、実際のユーザーのレビューや写真を使用して、ビジネスがニーズを満たしているかどうかを判断できます。 営業時間や連絡先の詳細などの基本的な情報に加え て、 HERE Places では人気のあるガイドの社説を掲載して、訪問する最適な場所を特定することもできます。

検索の実行に必要なデータがすでにダウンロードされている場合、データ接続が利用できないときはオフライン検索がサポートされます。

検索を実行する手順

  1. NMAResultListener 検索の完了を処理するプロトコルを実装します。
  2. NMAPlaces ファクトリを使用してリクエストを作成します。
  3. を呼び出して、リクエストを呼び出し NMARequest startWithListener:ます。
  4. NMAResultListener request:didCompleteWithData:error: コールバックは、リクエストが終了するとトリガーされます。
注 : Places API を使用するアプリケーションは、次の規定されたワークフローを遵守する必要があります。
  1. 検索
  2. 詳細リクエスト
  3. アクションを実行します
HERE ガイドラインに違反しているため、レスポンスからリンクされた結果をプリロードしないでください。パフォーマンスを向上させるために、結果をプリロードすることはできません。 使用制限の詳細については 'Places API ドキュメントの API 実装チェックリストの項を参照してください

検出リクエスト

HERE Places API では、次のディスカバリ要求がサポートされています リクエストは、のファクトリメソッドを使用して作成 NMAPlacesされます。

リクエスト NMAPlaces メソッド 目的
検索 createSearchRequestWithLocation: query: ユーザーが指定した検索条件に一致する場所を検索します。
Explore createExploreRequestWithLocation:searchArea:filters: 近く、または地図ビューポイントで人気順に並べ替えられた、興味のある場所を探します。 「 HERE の近くにある興味深い場所は何ですか?」という質問に回答しようとしている場合は、このタイプのリクエストを使用します。 結果は、任意で特定のカテゴリのセットに制限されることがあります。このカテゴリは、返された場所のフィルタとして機能します。
HERE createHereRequestWithLocation:filters: 特定の地点の近くにある名所を距離で並べ替えて検索することで、ユーザーが特定の場所の場所を特定できるようにします。 「この場所の近くに何がありますか?」という質問に回答しようとしている場合は、このタイプのリクエストを使用します。 または「現在地はどこですか?」 このエンドポイントを使用して、「チェックイン」 ( ユーザーの現在の位置にある場所を特定 ) や「タップしてこの場所に関する詳細情報を取得」などの機能を実装できます。
注 : 通常、最も近い既知の場所が HERE ディスカバリ要求とともに返されますが、特定の場所の不確実性が高い場合、不確実性の領域でより一般的な場所が優先され、その結果からより近い場所が除外されます。
周囲方向 createAroundRequestWithLocation:searchArea:filters: ユーザーが、位置精度パラメーターに基づいて、指定したポイントの近くに位置を要求できます。 そのポイントを囲む場所が近接した順に返されます。 このタイプのリクエストは、ユーザーの現在地周辺の場所がデバイスに表示される拡張現実などの機能を使用するアプリケーションを対象としています。 ユーザーに表示される可能性のある場所や、遠くにある重要な場所を提供することを目的としています。 Around 要求は実験的なものと見なされ、その動作と機能はまだ進化しています。 この機能の更新については、今後のドキュメントを参照してください。
次のコード例は、検索ディスカバリ要求を実行する方法を示しています。 request:didCompleteWithData:error コールバックメソッドを実装して NMAResultListener プロトコルを実装する必要があります。また、次の呼び出し request startWithListener: によって要求を初期化する必要があります。

// Sample Search request listener
@interface NMASearchTest : NSObject<NMAResultListener> {
  NMADiscoveryPage* _result;
}
@end
@implementation NMASearchTest

// NMAResultListener protocol callback implementation
- (void)request:(NMARequest*)request
    didCompleteWithData:(id)data
    error:(NSError*)error
{
  if ( ( [request isKindOfClass:[NMADiscoveryRequest class]]) &&
    ( error.code == NMARequestErrorNone ) )
  {
    // Process result NMADiscoveryPage objects
    _result = (NMADiscoveryPage*) data;
  }
  else
  {
    // Handle error
    ...
  }
}
- (void) startSearch
{
  // Create a request to search for restaurants in Vancouver
  NMAGeoCoordinates* vancouver =
  [[NMAGeoCoordinates alloc] initWithLatitude:49.2849
          longitude:-123.1252];

  NMADiscoveryRequest* request =
  [[NMAPlaces sharedPlaces] createSearchRequestWithLocation:vancouver
          query:@"restaurant"];

  // optionally, you can set a bounding box to limit the results within it.
  NMAGeoCoordinates *boundingTopLeftCoords = [[NMAGeoCoordinates alloc] initWithLatitude:49.277484 longitude:-123.133693];
  NMAGeoCoordinates *boundingBottomRightCoords = [[NMAGeoCoordinates alloc] initWithLatitude:49.257209 longitude:-123.11275];
  NMAGeoBoundingBox *bounding = [[NMAGeoBoundingBox alloc] initWithTopLeft:boundingTopLeftCoords bottomRight:boundingBottomRightCoords];

  request.viewport = bounding;

  // limit number of items in each result page to 10
  request.collectionSize = 10;

  NSError* error = [request startWithListener:self];
  if (error.code != NMARequestErrorNone)
  {
    // Handle request error
    ...
  }
}
@end

アプリケーションが最適な検索結果を取得できるようにする viewport には、バウンディング ボックスをプロパティに設定して、検索リクエストに位置情報コンテキストを設定します。 前の例では、を NMAGeoBoundingBox からのビューポイントで置き換えることもでき NMAMapViewます。

検索または探索の検出リクエストの結果はです NMADiscoveryPage。 は NMADiscoveryPage 、次のものを取得できる、ページ設定されたアイテムのコレクションを表します。
  • 次のページリクエスト - NMADiscoveryRequest 検索アイテムの追加ページを取得するために使用されます
  • 現在のページのアイテム - NMALink NSArray 、または NMAPlaceLink NMADiscoveryLink のいずれか

NMADiscoveryPage.nextPageRequest が nil の場合、追加の結果はありません。

次に例を示します。


...
@interface NMANextPageTest : NSObject<NMAResultListener> {
  NMADiscoveryPage* _page;  // valid NMADiscoveryPage instance
}
@end
@implementation NMANextPageTest
- (void)onNextPageAction
{
  NSError* error = [_page.nextPageRequest startWithListener:self];
  if ( error.code == NMARequestErrorNone )
  {
    // More data is available
  }
}

// NMAResultListener protocol callback implementation
- (void)request:(NMARequest*)request
    didCompleteWithData:(id)data
    error:(NSError*)error
{
  if ( ( [request isKindOfClass:[NMADiscoveryRequest class]] ) &&
    ( error.code == NMARequestErrorNone ) )
  {
    // Process NMADiscoveryPage objects
  }
  else
  {
    // Handle error
    ...
  }
}
...
@end
NMADiscoveryPage discoveryResults プロパティに NMALink は、オブジェクトの配列が含まれています。 アイテムは、実際に NMALink はサブクラスのコレクションです。
  • NMAPlaceLink - に関する検出情報を表し NMAPlaceます。 に NMAPlaceLink は、場所についての簡単な概要が含まれています。 場所の詳細については、 NMAPlaceLink 参照先の NMAPlace から参照できます。
  • NMADiscoveryLink - 追加 NMADiscoveryPage のインスタンスを取得するために使用される、検出関連の API リンクを表します。 このタイプのは NMALink 、探索または検索の HERE タイプの結果項目です。 NMADiscoveryLink 参照によって検出リクエストが絞り込まれ、より具体的な結果が得られます。 たとえば、は NMADiscoveryLink 発見リクエストにリンクして、「飲食」、「外出中」、「宿泊施設」などを検索できます。
NMADiscoveryPage 使用前に、各タイプのを確認することをお勧めします。 次の例では、 NMAPlace を介してがどのように取得されるかを示し NMAPlaceLinkます。

@interface NMASearchTest : NSObject<NMAResultListener> {
  NMADiscoveryPage* _result;
}
@end
@implementation NMASearchTest
// Retrieve the place details when the user selects a displayed PlaceLink.
- (void)onPlaceLinkSelected:(NMAPlaceLink*)placeLink
{
  NSError* error = [[placeLink detailsRequest] startWithListener:self];
  if ( error.code == NMARequestErrorNone )
  {
    // More data will available.
    ...
  }
}

// NMAResultListener protocol callback implementation
- (void)request:(NMARequest*)request
    didCompleteWithData:(id)data
    error:(NSError*)error
{
  if ( ( [request isKindOfClass:[NMADiscoveryRequest class]]) &&
     ( error.code == NMARequestErrorNone ) )
  {
    _result = (NMADiscoveryPage*) data;
    NSArray* discoveryResult = _result.discoveryResults;

    for ( NMALink* link in discoveryResult )
    {
      if ( link isKindOfClass:[NMADiscoveryLink class] )
      {
        NMADiscoveryLink* discoveryLink = (NMADiscoveryLink*) link;

        // NMADiscoveryLink can also be presented to the user.
        // When a NMADiscoveryLink is selected, another search request should be
        // performed to retrieve results for a specific category.
        ...
      }
      else if ( link isKindOfClass:[NMAPlaceLink class] )
      {
        NMAPlaceLink* placeLink = (NMAPlaceLink*) link;

        // NMAPlaceLink should be presented to the user, so the link can be
        // selected in order to retrieve additional details about a place
        // of interest.
        ...
      }
    }
  }
  else  if ( ( [request isKindOfClass:[NMAPlaceRequest class]]) &&
         ( error.code == NMARequestErrorNone ) )
  {
    NMAPlace* place = (NMAPlace*)data;
    // Access to additional details about a place of interest.
  }
  else
  {
    // Handle error
    ...
  }
}
@end

GitHub でサンプルを検索します

この機能を示す例について は、 https://github.com/heremaps/ (Obj-C) および https://github.com/heremaps/ (Swift) を参照してください。

NMAPlace クラス

NMAPlace このクラスは、さまざまな属性のコンテナとして機能する物理的な場所、場所に関するメディアのコレクション、および関連する場所のキーと値のペアに関する詳細なデータのセットを表します。 NMAPlace オブジェクトは特定のに属することができ、 NMACategory 次のような属性を持ちます。
  • 一意の識別子 (ID)
  • 名前
  • NMAPlaceLocation その場所の物理的な場所を表すオブジェクト NMAPlaceLocation 。この場所にアクセスするための住所と地理座標位置のリストも含まれています
  • NMACategory その場所に割り当てられているカテゴリにリンクするオブジェクトの配列
  • NMALink 提供された情報の起点へのリンクを含むオブジェクト。通常はサプライヤの Web サイトです
  • NSString オフライン検索でアイコンへの URL を表す ( オプション ) 場所のアイコンがアプリケーションに表示されます。
  • 関連する場所、ユーザーの評価、レビュー、その他の編集メディアなどのオプション情報

カテゴリフィルタ

美術館、レストラン、コーヒーショップなどのカテゴリに関心のある場所を関連付けることができます。 エクスプローラまたは HERE の検出リクエストを作成するときに、より具体的な結果セットを取得するためのカテゴリフィルタを提供することを選択できます。 たとえば、バンクーバー市庁舎の近くにある寿司屋を検索できます。

カテゴリのリストを取得するには、 NMAPlacestopLevelCategories メソッドを呼び出します。 このカテゴリのリストから、 1 つ以上のレベルのサブカテゴリを取得できます。 たとえば、「レストラン」カテゴリの「バー / パブ」などです。 カテゴリを作成したら NMACategoryFilter 、オブジェクトを作成し addCategoryFilterFromUniqueId てメソッドを呼び出します。 各 NMACategoryFilter オブジェクトは複数のカテゴリを表すことができます。


NSArray* categories = [[NMAPlaces sharedPlaces] topLevelCategories];

for (id category in categories)
{
  if (category.uniqueId == "restaurant" )
  {
    NMACategory* restCategory = category;
    NMAGeoCoordinates* vancouver = [[NMAGeoCoordinates alloc]
                    initWithLatitude:49.2849
                    longitude:-123.1252];

    NMACategoryFilter *categoryFilter = [NMACategoryFilter new];
    [categoryFilter addCategoryFilterFromUniqueId:restCategory.uniqueId];

    NMADiscoveryRequest* request = [ [NMAPlaces sharedPlaces]
                createHereRequestWithLocation:vancouver
                filters:categoryFilter];
    //...
  }
}
注 : ユーザーがのインスタンスを作成すると、カテゴリリストが取得さ NMAPlacesれ、自動的にキャッシュに保存されます。 ただし、ユーザーが以前 NMAPlaces にキャッシュされた一覧表を使用せずにロケールを変更したり、削除したりしてオフライン モードでデバイスを再起動した場合、デバイスが再びオンラインになったときにキャッシュが自動的に更新されないことがあります。

このシナリオを解決 refreshTopLevelCategoriesWithCompletion するには、メソッドを呼び出してカテゴリリストを手動で更新します。 topLevelCategories メソッドが返されない場合は、カテゴリリストが更新されたことを確認 nilできます。

AutoSuggest のリクエストを入力してください

HERE Places 検索 API では、テキスト自動結合リクエストもサポートされています。 このタイプのリクエストは、指定した場所のコンテキストおよび部分的な検索条件に関連付けられている、 インスタント結果 (NMAAutoSuggestTypePlace) および詳細な検索リンク (NMAAutoSuggestTypeSearch) のリストを取得するために使用されます。 たとえば、ベルリンで文字列「 REST 」を使用してリクエストを作成すると、結果には「レストラン」、「 REST area 」、「 Restorf 、 H ö hbeck 、 Germany 」などの検索語が含まれます。

注 : 現在、テキストの AutoSuggest 機能 はベータ版として提供されています。 API は予告なく変更されることがあります。 オフラインリクエストはサポートされていません。

テキストの自動集計を使用するには、次のようにリスナーを実装して NMAAutoSuggest のリストを処理し、 createAutoSuggestionRequestWithLocation:partialTerm: 呼び出します。

// Sample Search request listener
@interface NMATextAutoSuggestionSearchTest : NSObject<NMAResultListener> {

}
@end
@implementation NMATextAutoSuggestionSearchTest

// NMAResultListener protocol callback implementation
- (void)request:(NMARequest*)request
  didCompleteWithData:(id)data
      error:(NSError*)error
{
  if (([request isKindOfClass:[NMAAutoSuggestionRequest class]]) &&
     (error.code == NMARequestErrorNone))
  {
    // Results are held in an array of NMAAutoSuggest objects
    // You can then check the subclass type using the NMAAutoSuggest.type property
    NSArray* textAutoSuggestionResult = (NSArray*) data;
  }
  else
  {
    // Handle error
    ...
  }
}
- (void)startSearch
{
  NMAGeoCoordinates *vancouver =
      [[NMAGeoCoordinates alloc] initWithLatitude:49.2849
            longitude:-123.1252];

  // Use following filter to show results only in the Canada
  NMAAddressFilter *filter = [[NMAAddressFilter alloc] init];
  filter.countryCode = @"CAN";
  NMAAutoSuggestionRequest *request =
    [[NMAPlaces sharedPlaces] createAutoSuggestionRequestWithLocation:vancouver
      partialTerm:@"rest" filter:filter];

  // limit number of items in each result page to 10
  request.collectionSize = 10;

  NSError *error = [request startWithListener:self];
  if (error.code != NMARequestErrorNone)
  {
    // Handle request error
    ...
  }
}
@end

NMAAutoSuggestionRequestNMAAutoSuggest の例に示すように、まずオブジェクトタイプを確認することで、の結果を取得できます。 オブジェクトが NMAAutoSuggestTypeSearch の場合は、その NMADiscoveryRequest オブジェクトを通して追加のページ設定された結果が含まれます。 オブジェクトが NMAAutoSuggestTypePlace の場合は、その NMAPlaceRequest オブジェクトを使用して詳細情報を要求できます。

+(BOOL)checkAutoSuggestResults:(NSArray*)array
{
  for (id item in array) {
    NMAAutoSuggestType type = ((NMAAutoSuggest*)item).type;
    NSString *typeString;
    switch (type){
      caseNMAAutoSuggestTypePlace:
      {
        typeString = @"Place";
      }
        break;
      caseNMAAutoSuggestTypeSearch:
      {
        typeString = @"Search";
      }
        break;
    }

    NSLog(@"Type = %@", typeString);

    NMAAutoSuggest* suggestItem = (NMAAutoSuggest*)item;

    //Retrieve information such as suggestItem.title

    if (type == NMAAutoSuggestTypePlace) {

      NMAAutoSuggestPlace* suggestPlace = (NMAAutoSuggestPlace*)item;

      //Retrieve information such as suggestPlace.vicinityDescription

      NMAPlaceRequest* detailsRequest = suggestPlace.placeDetailsRequest;

      // Get NMAPlaceResult by calling detailsRequest startWithListener:
      // ...

    } else if (type == NMAAutoSuggestTypeSearch) {

      NMAAutoSuggestSearch* suggestSearch = (NMAAutoSuggestPlace*)item;

      //Retrieve information such as suggestSearch.position

      NMADiscoveryPage* discoveryPage;
      NMADiscoveryRequest* discoveryRequest = suggestSearch.suggestedSearchRequest;

      // Get discoveryPage by calling [discoveryRequest startWithListener:]
      // ...
    }
  }
  return YES;
}
      

外部参照

関心のある場所に は、 HERE SDK 外部の外部システムへの参照を含めることができます。 たとえば NMAPlace 、レストランを表すには、レストランレビューサービスのエントリへの外部参照を含めることもできます。 の各外部参照 NMAPlace は参照ソースに関連付けられており、各参照には 1 つ以上の識別子を含めることができます。

NMADiscoveryRequest およびでは、次の外部参照ソースがサポートされています NMAPlaceRequest
  • NMAPlacesSourcePVID - HERE Core マップの POI データのソース
  • "yelp" - Yelp ID のソース

外部参照は、 NMAPlaceLinkNMAPlaceLocation 、または NMAPlace の 1 つ以上の識別子の形式 NSString で返されます。 参照を要求するに NMARequest は、にソース(ディスカバリ要求など)を追加し、同じソース名を使用して結果から参照を取得する必要があります。 たとえば、


// Create a request to search for restaurants in Vancouver
NMAGeoCoordinates* vancouver =
[[NMAGeoCoordinates alloc] initWithLatitude:49.2849
        longitude:-123.1252];
NMADiscoveryRequest* request =
[[NMAPlaces sharedPlaces] createSearchRequestWithLocation:vancouver
        query:@"restaurant"];

// We also want to retrieve the Yelp ID external reference
[request addSource:@"yelp"];

request.collectionSize = 10;
NSError* error = [request startWithListener:self];

リクエストの実行が完了したら referenceIdentifiersForSource: 、次のようにメソッドを使用して結果を取得できます。


...
if ( resultLink isKindOfClass:[NMAPlaceLink class] )
{
  NMAPlaceLink* placeLink = (NMAPlaceLink*) resultLink;

  NSArray* yelpIds =
    [placeLink referenceIdentifiersForSource:@"yelp"];

  for(NSString* id in yelpIds) {
    NSLog(id); // retrieved Yelp ID
  }
}
...

追加の外部参照ソースは、次の例に示すように、詳細リクエストによってサポートされます。 たとえば detailsRequest 、のプロパティを使用し NMAPlaceLink て、詳細リクエストを実行して参照 ID を取得できます。

注 : 詳細リクエストを使用して、次の外部参照を取得できます。 [*] で示されているソースは createLookupRequestWithReferenceIdentifier:inSource: メソッドで使用できません。
  • NMAPlacesSourcePVID - HERE Core POI のソース
NMAPlaceRequest* placeDetailsRequest = receivedPlaceLink.detailsRequest;
[placeDetailsRequest addSource:NMAPlacesSourcePVID];
[placeDetailsRequest addSource:@"yelp"];
[placeDetailsRequest addSource:@"tripadvisor"];

[placeDetailsRequest startWithBlock:^(NMARequest *request, id data, NSError *error) {
  if (!error && data) {
    NMAPlace *place = (NMAPlace*)data;

    NSArray *pvids = [place referenceIdentifiersForSource:NMAPlacesSourcePVID];
    NSArray *yelpIds = [place referenceIdentifiersForSource:@"yelp”];
    NSArray *tripadvisorIds = [place referenceIdentifiersForSource:@"tripadvisor”];
  }
}];

逆のシナリオで外部 PVID 参照を使用して、createLookupRequestWithReferenceIdentifier:inSource: メソッドを使用して特定の NMAPlace を取得することもできます。 例 :


NMAPlaceRequest* request = [ [NMAPlaces sharedPlaces]
  createLookupRequestWithReferenceIdentifier:@"1126226306"
  inSource:NMAPlacesSourcePVID ];

ハイブリッド車検索

オフライン検索をサポート するために、 HERE SDK には、オンライン検索と比較して場所のサブセットが含まれている場所のデータベースが事前に読み込まれています。 インターネット接続が利用できず、既定の接続モードでプレース検索が実行された場合、このデータベースのエントリの基本的なプレース情報のみが返されます ( 評価やレビューなどのリッチデータは含まれません ) 。 ただし、インターネット接続が再確立される と、 HERE SDK はオンラインの場所の結果を再度取得します。