Directory

You can search for objects in the directory, get search suggestions and search results.

Usage scenarios

Typical scenarios of working with the directory:

• Search in a certain area. Example: find all coffee shops within a specified polygon on the map.
• Search in the area of ​​interest. Example: find all flower shops in the viewport of the map.
• Search near a certain point. Example: find public transport stops near the location of a user.
• Search within a point radius. Example: find all gas stations within a radius of 1000 m of the car destination.
• Search by object type. Example: find parking lots by the text query parking lots within a radius of 1000 m from the car destination.
• Search by object ID in the directory.

You can run these scenarios by building a search query in multiple ways:

• As a text query (fromQueryText() method) with different levels of precision: with a particular object name or with a category of interest.
• By specifying an ID of a particular rubric (fromRubricIds() method), organization (fromOrgId() method), or building (fromBuildingId() method).
• By specifying the coordinates of the search center (fromGeoPoint() method).

Creating a search engine

To search for objects in the directory, create a SearchManager object and call one of the methods that determines the directory operating mode:

• SearchManager.createOnlineManager() - creates an online directory.
• SearchManager.createOfflineManager() - creates an offline directory (preloaded data only).
• SearchManager.createSmartManager() - creates a combined directory that works primarily with online data and switches to offline mode when the network goes down.

An example of creating a search engine with an online directory:

val searchManager = SearchManager.createSmartManager(sdkContext)

Building a search query

Search in a certain area

To search for objects in a certain area, create a SearchQuery object using SearchQueryBuilder and pass it to the search() method. Specify a search area restriction as a polygon using the setSpatialRestriction() method:

val polygon = listOf(
    GeoPoint(latitude = 55.751244, longitude = 37.618423),
    GeoPoint(latitude = 55.760244, longitude = 37.628423),
    GeoPoint(latitude = 55.770244, longitude = 37.618423),
    GeoPoint(latitude = 55.751244, longitude = 37.608423)
)

val searchQuery = SearchQueryBuilder
    .fromQueryText("pizza")
    .setSpatialRestriction(polygon)
    .setPageSize(10)
    .build()

Search in the area of ​​interest

To search for objects in the area of interest, create a SearchQuery object using SearchQueryBuilder and pass it to the search() method. Specify the coordinates of the rectangular area of ​​interest using the setAreaOfInterest() method:

val areaOfInterest = GeoRect(
    GeoPoint(59.931, 30.344),
    GeoPoint(59.936, 30.351)
)
val searchQuery = SearchQueryBuilder
    .fromQueryText("text")
    .setAreaOfInterest(areaOfInterest)
    .build()

Search near a certain point

To search for objects near a certain point, create a SearchQuery object using SearchQueryBuilder and pass it to the search() method. Specify the coordinates of the search center point using the setGeoPoint() method:

val searchQuery = SearchQueryBuilder
    .fromQueryText("text")
    .setGeoPoint(GeoPoint(59.936, 30.351))
    .build()

Search within a point radius

To search for objects within a point radius, create a SearchQuery object using SearchQueryBuilder and pass it to the search() method. Specify the coordinates of the search center point using the setGeoPoint() method and the radius of the search area using the setRadius() method:

val searchQuery = SearchQueryBuilder
    .fromQueryText("text")
    .setGeoPoint(GeoPoint(59.936, 30.351))
    .setRadius(Meter(1000f))
    .build()

Search by object type

To search for objects by type, create a SearchQuery object using SearchQueryBuilder and pass it to the search() method. Specify the object type using the setAllowedResultTypes() method:

val searchQuery = SearchQueryBuilder
    .fromQueryText("text")
    .setAllowedResultTypes(allowedResultTypes = listOf(ObjectType.BUILDING))
    .build()

Search by object ID

If the object ID in the directory is known, to get information about the object, use the searchById() method:

searchManager.searchById(id).onResult { directoryObject ->
    Log.d("APP", "Object title: ${directoryObject.title}")
}

The method returns a deferred result DirectoryObject.

Getting search results

Calling the search() method returns a deferred SearchResult, which contains a paginated list of found objects (DirectoryObject):

searchManager.search(searchQuery).onResult { searchResult ->
    // Get the first object of the first page
    val directoryObject = searchResult.firstPage?.items?.getOrNull(0) ?: return
    Log.d("APP", "Object title: ${directoryObject.title}")
}

To get the next page of search results, call the fetchNextPage()page method, which returns a deferred result Page:

firstPage.fetchNextPage().onResult { nextPage
    val directoryObject = nextPage?.items?.getOrNull(0) ?: return
}

Search suggestions

You can build suggestions when text searching for objects (see Suggest API). To do this, create a SuggestQuery object using SuggestQueryBuilder and pass it to the suggest() method:

val query = SuggestQueryBuilder.fromQueryText("pizz").setLimit(10).build()

searchManager.suggest(query).onResult { suggestResult ->
    // Get the first suggestion from the list
    val firstSuggest = suggestResult.suggests?.getOrNull(0) ?: return
    Log.d("APP", "Suggestion title: ${firstSuggest.title}")
}

The method returns a deferred SuggestResult, which contains a list of suggestions (Suggest).

Information about entrances in the directory

You can search for addresses in the directory with the exact apartment or entrance number.

DgisObjectId contains two identifiers:

• objectId - stable numeric identifier of the object.
• entranceId - stable numeric identifier of the object entrance.

If the entranceId is non-zero, then the search result is not a building but a specific entrance.

If you need to draw a marker on a specific entrance or get its coordinates to calculate a route, do not use markerPosition. This property contains the position related to the marker of the building. To get the entrance position, use the information from entrances:

fun getMarkerPosition(directoryObject: DirectoryObject?) : GeoPoint?
{
    val entranceId = directoryObject?.id?.entranceId ?: 0L
    if (entranceId != 0L) {
        directoryObject?.buildingEntrances?.find { info -> info.id.entranceId == entranceId }?.let {
            return it.geometry?.entrancePoints?.firstOrNull() ?: directoryObject.markerPosition?.point
        }
    }
    return directoryObject?.markerPosition?.point
}