HERE Android SDK Developer's Guide

Natural Language Processing (NLP)

The Natural Language Processing (NLP) feature adds a "natural language" interface to the HERE Android SDK. For example, the end user may say "find me a gas station". This prompts the NLP interface to detect that the user wants to search for gas stations, and it then triggers a search via the HERE SDK, using Places to find gas stations and speak the results to the user.

Important: NLP is currently offered as a beta feature. APIs may change without notice. Do not use this feature in a commercial application.

NLP covers the main features offered by the HERE Android SDK: search, routing, navigation, and traffic. NLP also saves and handles context for the user's request. For example, 'find 3 gas stations” and then 'take me to the third one'.

Initialization

You can start using the NLP feature by initializing the Nlp class after you have successfully initialized the MapFragment in your application.

Nlp is a singleton, so you first need to retrieve the instance of it and then call init() to initialize the whole engine. The Nlp.init(Context, MapFragment, CollectionProvider, OnInitializationListener) method takes in the application context, the MapFragment object, a CollectionProvider (or null if you don't want to implement a collection feature) and an OnInitializationListener input parameter to signal the caller when initialization is completed and if it was successful.

// Create Map NLP object to control voice operations
// Pass Activity as a Context!
m_nlp = Nlp.getInstance();
m_nlp.init(AppActivity.this, mapFragment,
    m_nlpCollectionProvider, m_nlpListener);

private OnInitializationListener m_nlpListener =
  new OnInitializationListener() {
  @Override
  public void onComplete(Error error) {

    if (error == Error.NONE) {

      // Install earcons for ASR states indications. MUST
      m_nlp.setEarcons(raw.sk_start, raw.sk_stop, raw.sk_error);

      // Enable talk-back
      m_nlp.setTalkBackEnabled(true);

      // Set speech volume percentage
      m_nlp.setSpeechVolume(25);
    }
  }
};
Note: Nlp can only be used after it is successfully initialized.
Note: If you want to support a collection feature in your application via NLP, implement a CollectionProvider. If the CollectionProvider interface is not implemented, all collection related utterances results in "feature not supported" announcement to the user. Use cases for collection-handling includes saving a found place in a collection, creating a collection, renaming a favorite place, and deleting a collection.

Using the Nlp Class

When the Nlp initialization is successfully complete, you need to set listeners to receive callbacks when different utterances are said by the users. For example, if you want to know when the user says "search for restaurants, you need to override OnSearchListener callback. All available listeners are listed in the Nlp class definition.

private OnInitializationListener m_nlpListener = new OnInitializationListener() {
  @Override
  public void onComplete(Error error) {

    if (error == Error.NONE) {

      // Create handlers
      m_nlp.addListener(m_searchListener);
    }
  }
};

private OnSearchListener m_searchListener = new OnSearchListener() {
  @Override
  public void onStart(final String subject, final GeoBoundingBox box) {
    android.util.Log.d(TAG, "onStart: Search STRING start event");
  }

  @Override
  public void onStart(final CategoryFilter filter, final GeoBoundingBox box) {
    android.util.Log.d(TAG, "onStart: Search CATEGORY start event");
  }

  @Override
  public void onStart(final GeoCoordinate center) {
    android.util.Log.d(TAG, "onStart: Search REVERSE start event");
  }

  @Override
  public void onComplete(final Error error,
               final String searchString,
               final String whereString,
               final String nearString,
               List<PlaceLink> placeLinks) {
    android.util.Log.d(TAG, "onComplete: Search results are available");
    if (error == Error.NONE) {
      // Show all found places on the map.
    }
  }
};