HERE iOS SDK Developer's Guide

NMAPlaces

Class Summary

class NMAPlaces

Derived from: NSObject

Represents a factory for creating places requests.

Include: NMAKit.framework/headers/NMAPlaces.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMAPlaces

[For complete information, see the section Class Details]

Instance Method Summary

Table 1. Instance Methods
Instance Method Summary

-( NMADiscoveryRequest *) createAroundRequestWithLocation:( NMAGeoCoordinates *) location searchArea:( NMAGeoBoundingBox *) geoArea filters:( NMACategoryFilter *) filters

Creates a NMAPlaces around request using a specified location context, usually the location of the user

-( NMAAutoSuggestionRequest *) createAutoSuggestionRequestWithLocation:( NMAGeoCoordinates *) location partialTerm:(NSString *) partialTerm

Creates a NMAPlaces request to return lists of suggested search terms, instant results and refined search links related to a specified location context and partial search term

-( NMADiscoveryRequest *) createExploreRequestWithLocation:( NMAGeoCoordinates *) location searchArea:( NMAGeoBoundingBox *) geoArea filters:( NMACategoryFilter *) filters

Creates a NMAPlaces explore request using a specified location context and category filter

-( NMADiscoveryRequest *) createHereRequestWithLocation:( NMAGeoCoordinates *) location filters:( NMACategoryFilter *) filters

Creates a NMAPlaces "What's here?" request using a specified location context and category filter

-( NMAPlaceRequest *) createLookupRequestWithReferenceIdentifier:(NSString *) referenceIdentifier inSource:(NSString *) source

Creates a NMAPlaceRequest based on a reference identifier and source

-( NMADiscoveryRequest *) createSearchRequestWithLocation:( NMAGeoCoordinates *) location query:(NSString *) query

Creates a NMAPlaces search request using a specified location and query

-( NMASuggestionRequest *) createSuggestionRequestWithLocation:( NMAGeoCoordinates *) location partialTerm:(NSString *) partialTerm

Creates a NMAPlaces request to return a list of suggested search terms that are related to a specified location context and partial search term

-(void) refreshTopLevelCategoriesWithCompletion:( NMAPlacesCategoriesCompletionBlock ) completionBlock

Refresh the localized top level categories for Places Search

-(NSArray *) topLevelCategories

Return the localized top level categories for Places Search

Class Method Summary

Table 2. Class Methods
Class Methods

+( NMAPlaces *) sharedPlaces

Returns the NMAPlaces singleton instance

Class Details

Represents a factory for creating places requests.

The NMAPlaces service supports a variety of use cases that center around two major features:
  • Place discovery - helps users find places that are relevant to them.
  • Place information retrieval - provides detailed information about places in which users are interested.
For place discovery, the NMAPlaces API supports two use cases from which to choose according to the requirements for the application:
  • Search - finds places that match user-provided search terms.
  • Explore - guides users to relevant places nearby.

The NMAPlaces API defines resources that represent entry points for supported use cases, employing links to describe the application flow within a particular use case.

For example, the discovery request is an entry point to the NMAPlaces API resource. When an application user submits a discovery request to the search resource, the response contains, among other items, a list of links to places or to place resources. Each referenced place might have rich content associated with it, including ratings, images, reviews, editorials, and owner content. Each place also contains references to related places, which allow users to discover places relevant to or otherwise related to their original search.

Note:

NMAPlaces requires valid authentication credentials to be set via NMAApplicationContext. If valid credentials are not present the API may not function correctly or may stop functioning correctly in the future when server side configurations change.

Instance Method Details

-( NMADiscoveryRequest *) createAroundRequestWithLocation:( NMAGeoCoordinates *) location searchArea:( NMAGeoBoundingBox *) geoArea filters:( NMACategoryFilter *) filters

Creates a NMAPlaces around request using a specified location context, usually the location of the user. If a category filter is provided, the created request will limit results to include only items with categories specified in the filter.

This request is intended for applications that employ features such as augmented reality, where places around the user's current location are of most interest. It is intended to provide places that are likely to be visible to the user as well as important places that are further away. The places around the location context are returned in order of proximity.

Note that in addition to the requested location this search also considers the current device position as returned by NMAPositioningManager.

A search location context must be provided by setting a search location or a search area or a bounding map viewport. Failing to set a location context will result in an error NMARequestErrorInvalidParameter when executing the request.

Parameters:

  • location

    A NMAGeoCoordinates representing the location context used to search for nearby places

  • geoArea

    A NMAGeoBoundingBox representing the query's search area (this is an optional parameter and should not be set unless such functionality is explicitly intended in the application)

  • filters

    A NMACategoryFilter representing the category filter

Returns:

The NMADiscoveryRequest if parameters are valid

-( NMAAutoSuggestionRequest *) createAutoSuggestionRequestWithLocation:( NMAGeoCoordinates *) location partialTerm:(NSString *) partialTerm

Creates a NMAPlaces request to return lists of suggested search terms, instant results and refined search links related to a specified location context and partial search term.

IMPORTANT: This is a Beta API, and is subject to change without notice.

Note that this Autosuggest request supports online only. Please use createSuggestionRequestWithLocation:partialTerm for offline.

In addition to the requested location this search also considers the current device position as returned by NMAPositioningManager.

A search location context must be provided by setting a search location or a search area or a bounding map viewport. Failing to set a location context will result in an error NMARequestErrorInvalidParameter when executing the request.

Parameters:

  • location

    A NMAGeoCoordinates representing the query location context

  • partialTerm

    An NSString specifying the partial search term

Returns:

The NMAAutoSuggestionRequest if the location is valid, nil otherwise

-( NMADiscoveryRequest *) createExploreRequestWithLocation:( NMAGeoCoordinates *) location searchArea:( NMAGeoBoundingBox *) geoArea filters:( NMACategoryFilter *) filters

Creates a NMAPlaces explore request using a specified location context and category filter. If a category filter is provided, the created request will limit results to include only items with categories specified in the filter.

The results of the explore request is a list of nearby relevant places for a given positon. It answers the question "What interesting places are near a location?" The results returned are confined to those located in the current search area and are ordered by popularity.

Note that in addition to the requested location this search also considers the current device position as returned by NMAPositioningManager.

A search location context must be provided by setting a search location or a search area or a bounding map viewport. Failing to set a location context will result in an error NMARequestErrorInvalidParameter when executing the request.

Parameters:

  • location

    A NMAGeoCoordinates representing the location context used to search for nearby places

  • geoArea

    A NMAGeoBoundingBox representing the query's search area (this is an optional parameter and should not be set unless such functionality is explicitly intended in the application)

  • filters

    A NMACategoryFilter representing the category filter

Returns:

The NMADiscoveryRequest if parameters are valid

-( NMADiscoveryRequest *) createHereRequestWithLocation:( NMAGeoCoordinates *) location filters:( NMACategoryFilter *) filters

Creates a NMAPlaces "What's here?" request using a specified location context and category filter. If a category filter is provided, the created request will limit results to include only items with categories specified in the filter.

The results of the here request is a list of places with addresses that lie within the vicinity of the search location. The feature is typically used by applications that include "check-in" or "click on map to get more information" options.

Note that in addition to the requested location this search also considers the current device position as returned by NMAPositioningManager.

A search location context must be provided by setting a search location or a bounding map viewport. Failing to set a location context will result in an error NMARequestErrorInvalidParameter when executing the request.

Parameters:

  • location

    A NMAGeoCoordinates representing the location context used to search for nearby places

  • filters

    A NMACategoryFilter representing the category filter

Returns:

The NMADiscoveryRequest if both parameters are valid

-( NMAPlaceRequest *) createLookupRequestWithReferenceIdentifier:(NSString *) referenceIdentifier inSource:(NSString *) source

Creates a NMAPlaceRequest based on a reference identifier and source.

The supported sources are "pvid", "sharing", "venues", "venues.content", "venues.venue", "venues.destination", "building". See also Resource look-up .

"sharing" example:

The 'referenceIdentifier' argument to use is found in NMAPlace::viewUrl. The 'referenceIdentifier' is the last path segment of the View URI.

Using the following example View URI:

http://here.com/p/s-aWQ9Mjc2dTMzZGMtMzk0NGE0NzQ4YTYyNDk5Y2I3OTVjZjhiZWUzNDljOWM7bj1BbnRpcG9kZXM7Yz1jb2ZmZWUtdGVhO
3BoPSUyQjQ5MTc2MzgzNDAxMTg7bGF0PTUyLjUzMDkzO2xvbj0xMy40MDk5Mg

The sharing reference identifier is:

s-aWQ9Mjc2dTMzZGMtMzk0NGE0NzQ4YTYyNDk5Y2I3OTVjZjhiZWUzNDljOWM7bj1BbnRpcG9kZXM7Yz1jb2ZmZWUtdGVhO
3BoPSUyQjQ5MTc2MzgzNDAxMTg7bGF0PTUyLjUzMDkzO2xvbj0xMy40MDk5Mg

The reference source is NMAPlacesSourceSharing.

For example:

NMAPlaceRequest* request =
    [[NMAPlaces sharedPlaces] createLookupRequestWithReferenceIdentifier:    @"s-aWQ9Mjc2dTMzZGMtMzk0NGE0NzQ4YTYyNDk5Y2I3OTVjZjhiZWUzNDljOWM7bj1BbnRpcG9kZXM7Yz1jb2ZmZWUtdGVhO
      3BoPSUyQjQ5MTc2MzgzNDAxMTg7bGF0PTUyLjUzMDkzO2xvbj0xMy40MDk5Mg"
    inSource:NMAPlacesSourceSharing];

"venues.venue" example:

The venue reference identifier for Alexa Shopping Center is DM_7171. The reference source is NMAPlacesSourceVenuesVenue.

For example:

NMAPlaceRequest* request = [[NMAPlaces sharedPlaces]
createLookupRequestWithReferenceIdentifier:@"DM_7171" inSource:NMAPlacesSourceVenuesVenue];

Parameters:

  • referenceIdentifier

    The reference identifier of the requested NMAPlace in a specified source (ie Core POI, Venue).

  • source

    The NSString of the source in lower case (for examle pvid).

Returns:

The NMAPlaceRequest if the reference identifier is valid, nil otherwise

-( NMADiscoveryRequest *) createSearchRequestWithLocation:( NMAGeoCoordinates *) location query:(NSString *) query

Creates a NMAPlaces search request using a specified location and query.

The results of the search request are sets of places that match a user's search term in a specific location. Additional user's current position will also be sent to ensure you get the best results possible. The user's current position is only available if [ NMAPositioningManager active] is true.

The viewport is a bounding box used to perform the search. To ensure you get the best results possible, you should match the viewport to your map if there is a map visible to the user. (see also NMARequest::viewport).

A search location context must be provided by setting a search location or a bounding map viewport or both. Failing to set a location context will result in an error NMARequestErrorInvalidParameter when executing the request.

Parameters:

  • location

    A NMAGeoCoordinates representing the query's location context used to search for results that are appropriate to the query parameter.

  • query

    NSString specifying the kind of places to locate

Returns:

The NMADiscoveryRequest if both parameters are valid, nil otherwise.

-( NMASuggestionRequest *) createSuggestionRequestWithLocation:( NMAGeoCoordinates *) location partialTerm:(NSString *) partialTerm

Creates a NMAPlaces request to return a list of suggested search terms that are related to a specified location context and partial search term.

Note that in addition to the requested location this search also considers the current device position as returned by NMAPositioningManager.

A search location context must be provided by setting a search location or a search area or a bounding map viewport. Failing to set a location context will result in an error NMARequestErrorInvalidParameter when executing the request.

Parameters:

  • location

    A NMAGeoCoordinates representing the query location context

  • partialTerm

    An NSString specifying the partial search term

Returns:

The NMASuggestionRequest if the location is valid, nil otherwise

-(void) refreshTopLevelCategoriesWithCompletion:( NMAPlacesCategoriesCompletionBlock ) completionBlock

Refresh the localized top level categories for Places Search.

-(NSArray *) topLevelCategories

Return the localized top level categories for Places Search.

User can manually refresh the categories with refreshTopLevelCategoriesWithCompletion:

Note that the list of categories is cached. The update request to Places backend is made periodically and when device locale is changed. If there is no cache or cache is being updated, a nil is returned. User should try again later.

Returns:

An NSArray of localized NMACategory if available, nil otherwise

Class Method Details

+( NMAPlaces *) sharedPlaces

Returns the NMAPlaces singleton instance.

Note:

Use this method to obtain a NMAPlaces instance. Do not call init directly.

Returns:

shared NMAPlaces instance

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.