Instance Method

search

Retrieves the results of a search query.

Declaration

Number search(String|SearchAutocompleteResult query, function|SearchDelegate callback, optional SearchOptions options);

Parameters

query

A String or a SearchAutocompleteResult.

callback

A callback function or delegate object.

options

With the options hash, you can constrain the search to a desired area using the coordinate or region properties. A coordinate or region supplied here overrides the same property supplied to the mapkit.Search constructor. Another option is language. For example, { language: 'fr-CA' } tells the server to send results localized to Canadian French. If set, this option overrides the language provided to the search constructor.

Return Value

This method returns a request ID (integer) that can be passed to cancel to abort a pending request.

Discussion

The search method returns a set of locations that matches a user-entered query or a SearchAutocompleteResult.

The callback function is invoked on failure and success with two arguments, error and data. If the request is canceled before a response is received, this function is not called. The callback can also be a delegate object.

The arguments are:

  • error (Error). An error code and descriptive message.

  • data (Object). An object parsed from server-returned JSON. This object contains query, displayRegion, and places properties.

The data properties include:

  • query (String). The query corresponding to the results, if a SearchAutocompleteResult was not used to perform the search. Optional.

  • displayRegion (mapkit.CoordinateRegion). A region that encloses the search results. This property is not present if there are no results.

  • places (Array of Places). An array of Place objects. The places array is empty if there is no match.

In this example, search for "coffee shop" in and around the visible map area, and add the results as annotations.

var search = new mapkit.Search({ region: map.region });

search.search("coffee shop", function(error, data) {
    if (error) {
        // Handle search error
        return;
    }
    var annotations = data.places.map(function(place) {
        var annotation = new mapkit.MarkerAnnotation(place.coordinate);
        annotation.title = place.name;
        annotation.subtitle = place.formattedAddress;
        annotation.color = "#9B6134";
        return annotation;
    });
    map.showItems(annotations);
});

See Also

Performing a Search

SearchDelegate

An object or callback function called when performing a search or autocomplete request.

SearchOptions

Options you can provide when performing a search.

SearchResponse

The result of a search, including the original search query, the bounding region, and a list of places that match the query.