- Qt 6.12
- Qt Location
- QML Types
- PlaceSearchModel
- Qt 6.12.0 Reference Documentation

# PlaceSearchModel QML Type

Provides access to place search results. More...

Import Statement: | `import QtLocation 6.12`
Since: | QtLocation 5.5

- List of all members, including inherited members

## Properties

- categories : list<Category>
- count : int
- favoritesMatchParameters : VariantMap
- favoritesPlugin : Plugin
- incremental : bool `(since QtLocation 5.12)`
- limit : int
- nextPagesAvailable : bool
- plugin : Plugin
- previousPagesAvailable : bool
- recommendationId : string
- relevanceHint : enumeration
- searchArea : variant
- searchTerm : string
- status : enum
- visibilityScope : enum

## Signals

- dataChanged()

## Methods

- void cancel()
- Variant data(int index, string role)
- string errorString()
- void nextPage()
- void previousPage()
- void reset()
- void update()
- void updateWith(int proposedSearchIndex)

## Detailed Description

PlaceSearchModel provides a model of place search results within the searchArea. The searchTerm and categories properties can be set to restrict the search results to places matching those criteria.

The PlaceSearchModel returns both sponsored and organic search results. Sponsored search results will have the `sponsored` role set to true.

The model returns data for the following roles:

Role | Type | Description
--- | --- | ---
type | enum | The type of search result.
title | string | A string describing the search result.
icon | PlaceIcon | Icon representing the search result.
distance | real | Valid only when the `type` role is `PlaceResult`, the distance to the place from the center of the searchArea. If no searchArea has been specified, the distance is NaN.
place | Place | Valid only when the `type` role is `PlaceResult`, an object representing the place.
sponsored | bool | Valid only when the `type` role is `PlaceResult`, true if the search result is a sponsored result.

### Search Result Types

The `type` role can take on the following values:

PlaceSearchModel.UnknownSearchResult | The contents of the search result are unknown.
PlaceSearchModel.PlaceResult | The search result contains a place.
PlaceSearchModel.ProposedSearchResult | The search result contains a proposed search which may be relevant.

It can often be helpful to use a Loader to create a delegate that will choose different Components based on the search result type.

     Component {
         id: resultDelegate
         Loader {
             Component {
                 id: placeResult

                 Column {
                     Text { text: title }
                     Text { text: place.location.address.text }
                 }
             }

             Component {
                 id: otherResult
                 Text { text: title }
             }

             sourceComponent: type == PlaceSearchModel.PlaceResult ? placeResult :
                                                                     otherResult
         }
     }

## Detection of Updated and Removed Places

The PlaceSearchModel listens for places that have been updated or removed from its plugin's backend. If it detects that a place has been updated and that place is currently present in the model, then it will call Place::getDetails to refresh the details. If it detects that a place has been removed, then correspondingly the place will be removed from the model if it is currently present.

## Example

The following example shows how to use the PlaceSearchModel to search for Pizza restaurants in close proximity of a given position. A searchTerm and searchArea are provided to the model and update() is used to perform a lookup query. Note that the model does not incrementally fetch search results, but rather performs a single fetch when update() is run. The count is set to the number of search results returned during the fetch.

     import QtQuick
     import QtPositioning
     import QtLocation

     PlaceSearchModel {
         id: searchModel

         plugin: myPlugin

         searchTerm: "food"
         searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);

         Component.onCompleted: update()

     }

## Paging

The PlaceSearchModel API has some limited support for paging. The nextPage() and previousPage() functions as well as the limit property can be used to access paged search results. When the limit property is set the search result page contains at most limit entries (of type place result). For example, if the backend has 5 search results in total [a,b,c,d,e], and assuming the first page is shown and limit of 3 has been set then a,b,c is returned. The nextPage() would return d,e. The nextPagesAvailable and previousPagesAvailable properties can be used to check for further pages. At the moment the API does not support the means to retrieve the total number of items available from the backed. Note that support for nextPage(), previousPage() and limit can vary according to the plugin.

See also CategoryModel and QPlaceManager.

## Property Documentation

### categories : list<Category> `[read-only]`

This property holds a list of categories to be used when searching. Returned search results will be for places that match at least one of the categories.

### count : int `[read-only]`

This property holds the number of results the model has.

Note that it does not refer to the total number of search results available in the backend. The total number of search results is not currently supported by the API.

### favoritesMatchParameters : VariantMap

This property holds a set of parameters used to specify how search result places are matched to favorites in the favoritesPlugin.

By default the parameter map is empty and implies that the favorites plugin matches by alternative identifiers. Generally, an application developer will not need to set this property.

In cases where the favorites plugin does not support matching by alternative identifiers, then the plugin documentation should be consulted to see precisely what key-value parameters to set.

### favoritesPlugin : Plugin

This property holds the Plugin which will be used to search for favorites. Any places from the search which can be cross-referenced or matched in the favoritesPlugin will have their favorite property set to the corresponding Place from the favoritesPlugin.

If the favoritesPlugin is not set, the favorite property of the places in the results will always be null.

See also Favorites.

### incremental : bool `[since QtLocation 5.12]`

This property controls how paging will affect the PlaceSearchModel. If true, calling previousPage or nextPage will not reset the model, but new results will instead be appended to the model. Default is false.

This property was introduced in QtLocation 5.12.

### limit : int

This property holds the limit of the number of items that will be returned.

### nextPagesAvailable : bool `[read-only]`

This property holds whether there is one or more additional pages of search results available.

See also nextPage().

### plugin : Plugin

This property holds the Plugin which will be used to perform the search.

### previousPagesAvailable : bool `[read-only]`

This property holds whether there is one or more previous pages of search results available.

See also previousPage().

### recommendationId : string

This property holds the placeId to be used in order to find recommendations for similar places.

### relevanceHint : enumeration

This property holds a relevance hint used in the search query. The hint is given to the provider to help but not dictate the ranking of results. For example, the distance hint may give closer places a higher ranking but it does not necessarily mean the results will be strictly ordered according to distance. A provider may ignore the hint altogether.

SearchResultModel.UnspecifiedHint | No relevance hint is given to the provider.
SearchResultModel.DistanceHint | The distance of the place from the user's current location is important to the user. This hint is only meaningful when a circular search area is used.
SearchResultModel.LexicalPlaceNameHint | The lexical ordering of place names (in ascending alphabetical order) is relevant to the user. This hint is useful for providers based on a local data store.

### searchArea : variant

This property holds the search area. The search result returned by the model will be within the search area.

If this property is set to a geoCircle its radius property may be left unset, in which case the Plugin will choose an appropriate radius for the search.

Support for specifying a search area can vary according to the plugin backend implementation. For example, some may support a search center only while others may only support geo rectangles.

### searchTerm : string

This property holds search term used in query. The search term is a free-form text string.

### status : enum `[read-only]`

This property holds the status of the model. It can be one of:

PlaceSearchModel.Null | No search query has been executed. The model is empty.
PlaceSearchModel.Ready | The search query has completed, and the results are available.
PlaceSearchModel.Loading | A search query is currently being executed.
PlaceSearchModel.Error | An error occurred when executing the previous search query.

### visibilityScope : enum

This property holds the visibility scope of the places to search. Only places with the specified visibility will be returned in the search results.

The visibility scope can be one of:

Place.UnspecifiedVisibility | No explicit visibility scope specified, places with any visibility may be part of search results.
Place.DeviceVisibility | Only places stored on the local device will be part of the search results.
Place.PrivateVisibility | Only places that are private to the current user will be part of the search results.
Place.PublicVisibility | Only places that are public will be part of the search results.

## Signal Documentation

### dataChanged()

This signal is emitted when significant changes have been made to the underlying datastore.

Applications should act on this signal at their own discretion. The data provided by the model could be out of date and so the model should be reupdated sometime, however an immediate reupdate may be disconcerting to users if the results change without any action on their part.

The corresponding handler is `onDataChanged`.

Note: The corresponding handler is `onDataChanged`.

## Method Documentation

### void cancel()

Cancels an ongoing search operation immediately and sets the model status to PlaceSearchModel.Ready. The model retains any search results it had before the operation was started.

If an operation is not ongoing, invoking cancel() has no effect.

See also update() and status.

### Variant data(int index, string role)

Returns the data for a given role at the specified row index.

### string errorString()

This read-only property holds the textual presentation of the latest place search model error. If no error has occurred or if the model was cleared, an empty string is returned.

An empty string may also be returned if an error occurred which has no associated textual representation.

### void nextPage()

Updates the model to display the next page of search results. If there is no next page then this method does nothing.

### void previousPage()

Updates the model to display the previous page of search results. If there is no previous page then this method does nothing.

### void reset()

Resets the model. All search results are cleared, any outstanding requests are aborted and possible errors are cleared. Model status will be set to PlaceSearchModel.Null.

### void update()

Updates the model based on the provided query parameters. The model will be populated with a list of places matching the search parameters specified by the type's properties. Search criteria is specified by setting properties such as the searchTerm, categories, searchArea and limit. Support for these properties may vary according to plugin. `update()` then submits the set of criteria to the plugin to process.

While the model is updating the status of the model is set to `PlaceSearchModel.Loading`. If the model is successfully updated the status is set to `PlaceSearchModel.Ready`, while if it unsuccessfully completes, the status is set to `PlaceSearchModel.Error` and the model cleared.

     PlaceSearchModel {
         id: model
         plugin: backendPlugin
         searchArea: QtPositioning.circle(QtPositioning.coordinate(10, 10))
         ...
     }

     MouseArea {
         ...
         onClicked: {
             model.searchTerm = "pizza";
             model.categories = null;  //not searching by any category
             model.searchArea.center.latitude = -27.5;
             model.searchArea.center.longitude = 153;
             model.update();
         }
     }

See also cancel() and status.

### void updateWith(int proposedSearchIndex)

Updates the model based on the ProposedSearchResult at index proposedSearchIndex. The model will be populated with a list of places matching the proposed search. Model status will be set to PlaceSearchModel.Loading. If the model is updated successfully status will be set to PlaceSearchModel.Ready. If an error occurs status will be set to PlaceSearchModel.Error and the model cleared.

If proposedSearchIndex does not reference a ProposedSearchResult this method does nothing.