MapQuest iOS Search Ahead SDK

iPhones with MapQuest Maps

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.


  • 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

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 at Applications page.

Sample Key Page

If you don't have a MapQuest Developer Account you can sign up for one. Sign Up Here.

Xcode and Apple’s iOS SDK

You can get these for free from the Mac App Store. Download Xcode Here

Apple Developer Account (optional)

You can use your personal devices or Xcode’s iOS Simulator for this guide without an Apple Developer Account. If you want to distribute your app to others, you’ll need to sign up and pay for an account. Sign Up Here

Downloading the Search Ahead SDK


Download the zipped SDK that contains the framework and a resource bundle that need to be included in the project


Use the Search Ahead SDK within your own Xcode project using CocoaPods.

You need to include the following in the podfile:

source ''

pod 'MQSearchAhead', '~> 1.0.0'

Using your MapQuest Key in the SDK

To use the Search Ahead SDK in your app, you need to place your MapQuest Key inside the app’s Info.plist file:

  1. In the Project navigator (in the left sidebar), find your app’s Info.plist.
  2. Select the “Information Property List” row at the top, and go to Editor ‣ Add Item.
  3. In the new row that is inserted, set the Key to MQApplicationKey and set the Value to your Key.


Host app developers instantiate MQSearchAheadService which provides a query method to receive results asynchronously. When calling the Search Ahead service you will pass in 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.

The Objective-C and Swift examples here demonstrate how to do a simple search.

@import MQSearchAhead;

MQSearchAheadService* searchAheadService = [MQSearchAheadService new];
NSArray* collections = @[MQSearchAheadCollectionAirport, MQSearchAheadCollectionAddress, MQSearchAheadCollectionPOI, MQSearchAheadCollectionFranchise];
CLLocationManager* locationManager = [CLLocationManager new];

if (searchText.length < 2 || locationManager.location == nil) return;

MQSearchAheadOptions* options = [MQSearchAheadOptions new];
options.limit = 10;
options.includesFeedback = YES;

[searchAheadService predictResultsForQuery: @"MapQuest"
                               collections: collections
                                  location: location.coordinate,
                                   options: options
                                   success:^(MQSearchAheadResponse *response) {
                                      NSArray *results = response.results;
                                      if (results.count == 0) return;
                                      NSLog(@"%@", [results description]);
                                  failure:^(NSError *error) {
                                   NSLog(@"%@", [error localizedDescription]);
import MQSearchAhead

let searchAheadService = MQSearchAheadService()
let collections = [MQSearchAheadCollectionAirport, MQSearchAheadCollectionAddress, MQSearchAheadCollectionPOI, MQSearchAheadCollectionFranchise];
let locationManager = CLLocationManager()

// Continue only ifthe text is over 2 characters long, and there is a location
guard searchText.count > 1, let location = locationManager.location else {

let options = MQSearchAheadOptions()
options.limit = 10
options.includesFeedback = true

searchAheadService.predictResults(forQuery: "MapQuest",
                               collections: collections,
                                  location: location.coordinate,
                                   options: options,
                                   success: { [weak self] searchAheadResponse in

  guard let strongSelf = self, let results = searchAheadResponse?.results else { return }


  }, failure: { [weak self] error in
      guard let error = error else { return }


Search Parameters

For each call to the Search Ahead service you pass in a query and collection, as well as success/failure blocks. You can also pass in a geographic location to improve relevance of results


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.


The following collections are currently supported: MQSearchAheadCollectionAddress, MQSearchAheadCollectionAdminArea, MQSearchAheadCollectionAirport, MQSearchAheadCollectionPOI, MQSearchAheadCollectionCategory, and MQSearchAheadCollectionFranchise.

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.

Search Options

MQSearchAhead provides a simple class for you to set a search limit, language, and include feedback URls.


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.


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


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.

MQSearchAheadOptions* options = [MQSearchAheadOptions new];
options.limit = 10;
options.includesFeedback = YES;
options.language = @"es_US"; // US Spanish
let options = MQSearchAheadOptions()
options.limit = 10
options.includesFeedback = true
options.language = "es"US" // US Spanish

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

Supporting Documentation