Location and Maps Programming Guide

Enabling Search

To support searches based on user-entered queries, Map Kit provides the MKLocalSearch API. Apps can use this API to perform searches for locations that users describe by name, address, or type, such as coffee or theater.

Although local search and geocoding are similar, they support different use cases. Use geocoding when you want to convert between map coordinates and a structured address, such as an Address Book address. Use local search when you want to find a set of locations that match the user’s input.

Note: Search requests made using the MKLocalSearch API are server-based and require a network connection.

There are no request limits per app or developer ID, so well-written apps that operate correctly should experience no problems. However, throttling may occur in a poorly written app that creates extremely large numbers of requests.

To search for a location that matches the query a user types into a search field:

Create an MKLocalSearchRequest object and specify a string that contains the user’s natural-language query.

(Optional) Define a geographical region to narrow the search results. It’s recommended that you define a region to ensure that the user gets relevant results.

Create an MKLocalSearch object and initialize it with the search request you created in step 1.

Each MKLocalSearch object performs only one search; if you want to perform multiple searches, you have to define multiple search requests and use them to create multiple search objects. Because the search is performed asynchronously, you can create and begin multiple searches in parallel and handle the results as they arrive.

The results of a local search are provided as a set of MKMapItem objects. Each map item object contains the following attributes:

The map coordinates of the location

A structured address that represents the location

If the location is a business, the name, phone number, and URL associated with the business might be available

Listing 8-1 shows one way to create a search request, initiate a local search, and display the results as annotations on a map.