MapQuest Android Search Ahead SDK

Search Ahead is a spatially-aware predictive search engine most commonly used to implement 'type ahead' or autocomplete-like functionality within an application, to provide a list of suggestions to the user that refreshes as the user is typing. This SDK will return address, administrative area (city, state, postal code), airport, category, franchise, and POI suggestions based on just a few characters.

Features

• Spatially-aware predictive search provides autocomplete-like functionality
• Collections organize data types to limit the results to your needs
• Geographic Context used for searching, ranking, and ordering results
• Language Support for US English and US Spanish
• Providing Feedback that can be used to enhance the quality of the results returned from the Search Ahead

Complementary APIs

The following APIs are often used with the Search Ahead SDK and are currently being used within the sample app.

• Maps SDK : used for the MapView as demonstrated in the Sample Application; further documentation is available here
• Navigation SDK : full documentation available here

Getting Started

Project Setup and Configuration

• Create a new Android project; note that the minimum Android SDK version supported by the MapQuest Search Ahead SDK is API level 16.

• Add the following to the top of your app’s build.gradle file -- such that it includes the maven URL for the MapQuest artifacts repository:

  allprojects {
      repositories {
          jcenter()
          maven {
              url "https://maven.google.com"
          }
          maven {
              url "http://artifactory.cloud.mapquest.com/artifactory/et-android-binaries"
          }
      }
  }

• Also add the following items under the dependencies section of the build.gradle file for the app:

  dependencies {
      compile('com.mapquest:searchahead:1.3.1)
  }

MapQuest Key

In order to use MapQuest APIs and SDKs you will need a MapQuest key. We use this key to associate your requests to APIs with your account. You can find your existing keys or create a new one on the Applications page.

If you don't have a MapQuest Developer Account you can Sign Up Here.

Using your MapQuest Key in the SDK

Once you have a MapQuest Key, per above, create a new file named mapquest.properties in the app directory of your project, containing the following single-line entry:

api_key=[PUT_YOUR_API_KEY_HERE]

Then, add the following items under the android section of the build.gradle file for the app:

applicationVariants.all { variant ->
     variant.buildConfigField "String", "API_KEY", getApiKey() // Provides key for the Navigation SDK
     variant.resValue "string", "API_KEY", getApiKey()         // Provides key for the MapView used in app layouts
 }

Per the above, also add the following method (at the top-level) to the build.gradle for the app -- to define the getApiKey() method:

def getApiKey() {
    def props = new Properties()
    file("mapquest.properties").withInputStream { props.load(it) }
    return "\"" + props.getProperty("api_key") + "\""
}

Quickstart

Host app developers instantiate SearchAheadService which provides a query method to receive results asynchronously. When calling the Search Ahead service you will pass in a SearchAheadQuery which provides a list of collections that define what categories of data the service returns. You can also provide a limit to the number of results as well as a center location for geographic context.

private SearchAheadService mSearchAheadServiceV3;
mSearchAheadServiceV3 = new SearchAheadService(this, API_KEY);
String queryString = "1555";
List searchCollections = Arrays.asList(SearchCollection.AIRPORT, SearchCollection.ADMINAREA,
        SearchCollection.ADDRESS);
try {
    SearchAheadQuery query = new SearchAheadQuery.Builder(queryString, searchCollections).location(DENVER_LATLNG).build();
    mSearchAheadServiceV3.predictResultsFromQuery(query,
            new SearchAheadService.SearchAheadResponseCallback() {

                @Override
                public void onSuccess(@NonNull SearchAheadResponse searchAheadResponse) {
                    Log.i(TAG, "Search Ahead V3 Success - Response: " + searchAheadResponse);
                }

                @Override
                public void onError(Exception e) {
                    Log.e(TAG, "Search Ahead V3 Failure", e);
                }
            });
} catch (IllegalQueryParameterException e) {
    L.e("Error performing search", e);
}

Functionality

Search Query

For each call to the Search Ahead service you pass in a query that includes the search term, the search collections, and optionally a set of parameters. You can also pass in a geographic location to improve relevance of results

Query

A query phrase. The phrase can be incomplete, in which case its last term is treated as a prefix during matching. Address queries must begin with a street number. Minimum/Max length: 2/100 characters.

Collection

The following collections are currently supported: ADDRESS, ADMINAREA, AIRPORT, POI, CATEGORY, and FRANCHISE.

Geographic Location

The geographic context used for searching, ranking, and ordering results. Supports a point defining the geographic "center" of the query. While this parameter is not required, it is highly recommended that it be provided in order to improve relevance of results.

Feedback

If set to true, generated feedback URI templates will be returned in the response.

MapQuest provides a feedback API that can be used to enhance the quality of the results returned from the Search Ahead API. Usage of this service is optional, but if you wish to participate you will receive a MQSearchAheadFeedback object in the MQSearchAheadResponse response. You can then use the resulting URLs when the item is displayed in a list or on a map, or when clicked.

For more information on providing feedback, see the Providing Feedback page.

Limit

The maximum number of results to return. Must lie in the range [1, 15].

Language

Language allows the navigation prompts, instructions, and maneuvers to be localized in a supported language. Current supported languages include (default) US English en_US and US Spanish es_US.

Take a look at our Navigation SDK Reference Sample Application code to see a complete example of how to leverage the MQSearchAhead Android SDK.

Supporting Documentation