Справочник
Вы можете искать объекты в справочнике 2ГИС, обрабатывать результаты поиска, а также использовать подсказки для уточнения поисковых запросов. В справочнике вы можете найти информацию по объектам следующих типов:
- компании и их филиалы;
- здания;
- парковки;
- остановки общественного транспорта и станции метро;
- дороги (улицы, перекрёстки, проезды);
- населённые пункты разного размера (страны, города, регионы, деревни, микрорайоны и т.д.);
- различные площадные объекты (парки, пляжи и т.д.).
Полный список доступных типов объектов см. в описании класса ObjectType.
Чтобы начать работу со справочником:
- Создайте поисковый движок.
- Сформируйте поисковый запрос.
- Получите, обработайте и отобразите на карте результаты поиска.
Создание поисковика
Для поиска объектов в справочнике создайте объект SearchManager и вызовите один из методов, который определяет режим работы справочника:
- SearchManager.createOnlineManager() — создаёт онлайн-справочник.
SearchManager.createOfflineManager()— создаёт офлайн-справочник, работающий только с предзагруженными данными. Метод доступен в Full-версии SDK.SearchManager.createSmartManager()— создаёт комбинированный справочник, работающий с онлайн-данными при наличии сети и с предзагруженными данными при отсутствии сети. Метод доступен в Full-версии SDK.
Пример создания поисковика с онлайн-справочником:
import { SearchManager } from '@2gis/dgis-mobile-sdk-full';
const onlineSearchManager = SearchManager.createOnlineManager(context);
Некоторые методы работают только в определённом режиме справочника. Возможные ограничения указаны в описании методов.
Формирование поискового запроса
Чтобы отправить поисковый запрос, создайте объект SearchQuery с помощью SearchQueryBuilder и передайте его в метод search().
Поисковый запрос должен состоять из трёх логических компонентов:
-
Запрос для поиска объекта (что нужно искать?). Вы можете сформулировать запрос с помощью одного из методов ниже:
-
Из текстовой строки с помощью метода setQueryText(). Вы можете сформулировать текстовый запрос для поиска конкретного объекта (
храм Василия Блаженного) или для получения списка множества объектов по критерию (магазины музыкальных инструментов). -
По идентификаторам рубрик с помощью метода setRubricIds(). Этот способ полезен для создания выборки объектов определённого типа.
-
По идентификатору:
- Организации с помощью метода setOrgId(). Если у компании несколько филиалов, в ответе будут перечислены все точки.
- Зданий с помощью метода setBuildingIds().
- Любых объектов с помощью методов поискового движка searchByIds() и searchByDirectoryObjectIds().
-
-
Геоограничение поиска (где нужно искать?). Вы можете ограничить зону поиска с помощью одного из методов ниже:
-
Поиск внутри полигона: задайте область поиска с помощью метода setRestrictionGeometry() и объекта PolygonGeometry.
-
Поиск в прямоугольной области интереса: задайте координаты с помощью метода setAreaOfInterest(). Этот метод задаёт приоритетную зону поиска, но не ограничивает поиск строго: если внутри области интереса результаты не найдены, поиск продолжится за пределами области.
-
Поиск в радиусе вокруг точки: задайте центр поиска с помощью метода setRestrictionGeometry() и объекта PointGeometry, а радиус — с помощью метода setRadius().
-
Произвольный запрос: если запрос для поиска объекта сформирован с помощью метода setQueryText(), вы можете в этом же тексте указать и геоограничение (
цветы у Бауманской).
-
-
(Необязательный компонент) Дополнительные ограничения результатов поиска с помощью одного или нескольких методов ниже:
- Поиск объектов только определённого типа: перечислите интересующие вас типы объектов с помощью метода setAllowedResultTypes() (например, только здания).
- Фильтрация результатов: задайте критерий фильтрации с помощью метода setDirectoryFilter() (например, по времени работы).
- Сортировка результатов: задайте критерий сортировки с помощью метода setSortingType() (например, по рейтингу).
- Количество результатов на странице: задайте ограничение с помощью метода setPageSize().
- Номер страницы поисковой выдачи: по умолчанию возвращается первая страница. Чтобы получить следующие страницы, используйте метод fetchNextPage().
- Локаль для поискового запроса: задайте язык и регион с помощью метода setLocale().
Примеры
-
Найти рестораны итальянской кухни в Пресненском районе Москвы, которые открыты сейчас, с сортировкой по рейтингу:
import {
DirectoryFilter,
IsOpenNow,
SearchQueryBuilder,
SortingType,
WorkTimeFilter,
} from '@2gis/dgis-mobile-sdk-full';
const filter = new DirectoryFilter({
workTime: WorkTimeFilter.isOpenNow(new IsOpenNow({})),
dynamic: [],
});
const searchQuery = SearchQueryBuilder.fromQueryText(
'рестораны итальянской кухни в Пресненском районе Москвы',
)
.setDirectoryFilter(filter)
.setSortingType(SortingType.ByRating)
.setPageSize(10)
.build(); -
Найти все парковки в радиусе 1 км с сортировкой по удалённости:
import {
GeoPoint,
Latitude,
Longitude,
Meter,
ObjectType,
SearchQueryBuilder,
SortingType,
} from '@2gis/dgis-mobile-sdk-full';
const searchQuery = SearchQueryBuilder.fromQueryText('Парковки')
.setAllowedResultTypes([ObjectType.Parking])
.setGeoPoint(
new GeoPoint({
latitude: new Latitude({ value: 59.936 }),
longitude: new Longitude({ value: 30.351 }),
}),
)
.setRadius(new Meter({ value: 1000 }))
.setSortingType(SortingType.ByDistance)
.build(); -
Найти все населённые пункты (города, деревни, посёлки и т.д.) внутри полигона:
import {
GeoPoint,
Latitude,
Longitude,
ObjectType,
PolygonGeometry,
SearchQueryBuilder,
} from '@2gis/dgis-mobile-sdk-full';
const point = (latitude: number, longitude: number) =>
new GeoPoint({
latitude: new Latitude({ value: latitude }),
longitude: new Longitude({ value: longitude }),
});
const polygon = new PolygonGeometry([
[
point(55.7, 37.5),
point(55.8, 37.5),
point(55.8, 37.7),
point(55.7, 37.7),
],
]);
const searchQuery = SearchQueryBuilder.fromQueryText('название города')
.setAllowedResultTypes([
ObjectType.AdmDivCity,
ObjectType.AdmDivSettlement,
])
.setRestrictionGeometry(polygon)
.build(); -
Найти все объекты, которые оказывают услуги печати документов, в области интереса:
import {
GeoPoint,
GeoRect,
Latitude,
Longitude,
SearchQueryBuilder,
} from '@2gis/dgis-mobile-sdk-full';
const point = (latitude: number, longitude: number) =>
new GeoPoint({
latitude: new Latitude({ value: latitude }),
longitude: new Longitude({ value: longitude }),
});
const areaOfInterest = new GeoRect({
southWestPoint: point(59.931, 30.344),
northEastPoint: point(59.936, 30.351),
});
const searchQuery = SearchQueryBuilder.fromQueryText('печать документов')
.setAreaOfInterest(areaOfInterest)
.build(); -
Найти все компании по адресу «Новосибирск, площадь Карла Маркса, 7»:
import {
ObjectType,
SearchQueryBuilder,
} from '@2gis/dgis-mobile-sdk-full';
const searchQuery = SearchQueryBuilder.fromQueryText(
'Новосибирск, площадь Карла Маркса, 7',
)
.setAllowedResultTypes([ObjectType.Branch])
.setPageSize(10)
.build(); -
Найти все филиалы компании по известному идентификатору:
import { OrgId, SearchQueryBuilder } from '@2gis/dgis-mobile-sdk-full';
const id = 4504136498310300n;
const searchQuery = SearchQueryBuilder.fromOrgId(
new OrgId({ value: id }),
).build(); -
Найти конкретный объект по известному идентификатору:
const future = searchManager.searchById('70000001006378335');
future.onComplete(
object => {
console.log(object?.title);
future.destroy();
},
error => {
console.warn(error);
},
);
Геокодирование
С помощью SDK вы можете решать задачи геокодирования: определять координаты объекта на карте по его адресу (прямое геокодирование) и наоборот, определять адрес объекта на карте по его координатам (обратное геокодирование).
Прямое геокодирование
Чтобы получить координаты объекта по его адресу, сформируйте поисковый запрос, указав следующие данные:
-
Адрес в текстовом запросе с помощью метода fromQueryText().
Для более точных результатов укажите в тексте город (посёлок, деревню), где выполняется поиск. Название небольшого населённого пункта (например, деревни) рекомендуется указывать вместе с названием области и другими объединениями, к которым он относится (например, сельским или городским поселением).
-
(Рекомендуется) Тип объекта, координаты которого нужно получить, с помощью метода setAllowedResultTypes().
-
(Рекомендуется) Область поиска с помощью метода setAreaOfInterest().
Например, чтобы получить координаты здания по адресу «Москва, ул. Тверская 19а»:
const geocodingQuery = SearchQueryBuilder.fromQueryText('Москва, Тверская 19а')
.setAreaOfInterest(visibleRect)
.build();
В результате поиска вы получите объект справочника DirectoryObject. Координаты объекта будут представлены в поле markerPosition в виде объекта GeoPointWithElevation. Пример:
markerPosition:
GeoPointWithElevation {
latitude: Latitude { value: 55.7659 },
longitude: Longitude { value: 37.602827 },
elevation: Elevation { value: 18 },
},
Подробнее о другой информации в результатах поиска см. в разделе Структура данных объекта.
Обратное геокодирование
Чтобы получить адрес объекта по его координатам, сформируйте поисковый запрос, указав координаты объекта как строгую геометрию поиска. Используйте метод setRestrictionGeometry() и объект PointGeometry:
import {
GeoPoint,
Latitude,
Longitude,
PointGeometry,
SearchQueryBuilder,
} from '@2gis/dgis-mobile-sdk-full';
const searchQuery = new SearchQueryBuilder()
.setRestrictionGeometry(
new PointGeometry(
new GeoPoint({
latitude: new Latitude({ value: 55.7659 }),
longitude: new Longitude({ value: 37.602827 }),
}),
),
)
.build();
В результате поиска вы получите объекты справочника DirectoryObject. Адрес каждого объекта будет представлен в поле address в виде объекта Address. Пример:
address:
Address(
drillDown: [
AddressAdmDiv(type: 'country', name: 'Россия'),
AddressAdmDiv(type: 'region', name: 'Москва'),
AddressAdmDiv(type: 'city', name: 'Москва'),
AddressAdmDiv(type: 'district', name: 'Тверской'),
],
components: [
AddressComponent(
AddressStreet(
street: 'Тверская улица',
number: '19а',
fiasCode: null,
),
),
],
buildingName: null,
buildingId: BuildingId(value: 4504235282747324),
postCode: '125009',
buildingCode: null,
fiasCode: null,
addressComment: '1-2 этаж',
),
Подробнее о другой информации в результатах поиска см. в разделе Структура данных объекта.
Изменение параметров поиска
Вы можете изменять или дополнять параметры уже созданного поискового запроса. Для этого создайте новый объект SearchQuery, укажите существующий запрос с помощью метода fromQuery() и укажите параметры, которые нужно дополнительно применить. Например, изменить тип сортировки результатов при поиске парковок:
import {
GeoPoint,
Latitude,
Longitude,
Meter,
ObjectType,
SearchQueryBuilder,
SortingType,
} from '@2gis/dgis-mobile-sdk-full';
const searchQuery = SearchQueryBuilder.fromQueryText('Парковки')
.setAllowedResultTypes([ObjectType.Parking])
.setGeoPoint(
new GeoPoint({
latitude: new Latitude({ value: 59.936 }),
longitude: new Longitude({ value: 30.351 }),
}),
)
.setRadius(new Meter({ value: 1000 }))
.setSortingType(SortingType.ByDistance)
.build();
const searchQueryUpdated = SearchQueryBuilder.fromQuery(searchQuery)
.setSortingType(SortingType.ByRating)
.build();
Остальные параметры изначального запроса сохраняются.
Получение результатов поиска
Вызов метода SearchManager.search() возвращает отложенный результат Future<SearchResult>, содержащий список найденных объектов (DirectoryObject), разделенный на страницы. Первая страница результатов поиска доступна через свойство firstPage.
const future = searchManager.search(textQuery);
future.onComplete(
result => {
const firstPage = result.firstPage;
const objects = firstPage?.items ?? [];
objects.forEach(object => {
console.log(object.title, object.subtitle);
});
future.destroy();
},
error => {
console.warn(error);
},
);
Чтобы получить следующую страницу, вызовите метод страницы fetchNextPage(), который вернёт отложенный результат Page:
const nextPageFuture = firstPage.fetchNextPage();
nextPageFuture.onComplete(
page => {
console.log(page?.items ?? []);
nextPageFuture.destroy();
},
error => {
console.warn(error);
},
);
Отображение результатов на карте
Координаты всех найденных объектов возвращаются в поле itemMarkerInfos результата поиска SearchResult в виде списка элементов ItemMarkerInfo. Список может содержать не более 15000 элементов.
Чтобы отобразить на карте маркеры всех найденных объектов:
- Подготовьте список объектов Marker. Чтобы задать позицию маркера (параметр
position), используйте координаты из поля ItemMarkerInfo.geoPoint. - Добавьте готовый набор маркеров на карту с помощью метода
addObjects()менеджера объектов MapObjectManager. Подробнее см. в инструкции Добавление нескольких объектов на карту.
import {
ImageLoader,
MapObjectManager,
Marker,
MarkerOptions,
type ItemMarkerInfo,
type Map,
type SearchResult,
} from '@2gis/dgis-mobile-sdk-full';
async function displaySearchResultMarkers(
map: Map,
searchResult: SearchResult,
) {
// Получить данные для маркеров из результатов поиска
const markerInfosFuture = searchResult.itemMarkerInfos;
const markerInfos = await new Promise<ItemMarkerInfo[] | null>(
(resolve, reject) => {
markerInfosFuture.onComplete(
result => {
markerInfosFuture.destroy();
resolve(result);
},
error => {
reject(error);
},
);
},
);
if (markerInfos === null) {
return;
}
// Загрузить иконку маркера
const imageLoader = new ImageLoader(context);
const icon = await imageLoader.loadPngFromAsset(
'map/marker.png',
48,
48,
);
// Подготовить список маркеров
const markers = markerInfos.map(
itemMarkerInfo =>
new Marker(
new MarkerOptions({
position: itemMarkerInfo.geoPoint,
icon,
}),
),
);
// Создать менеджер объектов и добавить маркеры на карту
const mapObjectManager = new MapObjectManager(map, null);
mapObjectManager.addObjects(markers);
}
Структура данных объекта
Результаты поиска по справочнику представлены в виде списка объектов DirectoryObject с наборами свойств. В зависимости от типа объекта часть свойств может не содержать значений.
Получение некоторой информации об объектах доступно при дополнительной настройке ключа за отдельную плату: см. описания полей объектов DirectoryObject, Address и ItemMarkerInfo. Чтобы обновить настройки вашего ключа доступа, обратитесь в службу поддержки 2ГИС.
-
Основные свойства для классификации объекта:
- Тип объекта (
types) из ObjectType. Один объект может относиться к нескольким типам (например, ТЦ Сан Сити — это одновременно и филиал организации и здание). В этом случае все типы будут перечислены в списке, где первый элемент — основной тип объекта. - Название объекта (
title) в зависимости от его типа: название организации, достопримечательности, географического объекта. Для жилых домов без названия — адрес. - Подтип объекта (
subtitle) для уточнения. Например, кофейня как подтип организации или жилой дом как подтип здания. - Описание объекта (
description). - Категории, к которым относится объект (
rubricIds). - Идентификатор организации в справочнике и информация о ней (
orgInfo). Для компаний с множеством филиалов — информация о головной организации. - (Данные по запросу) Объединение объектов разного типа в одной карточке справочника (
group). Подробнее см. ниже.
- Тип объекта (
-
Уникальный идентификатор объекта в справочнике (
id). Для компаний с множеством филиалов — идентификатор конкретного филиала. -
Географические свойства:
- Координаты для размещения маркера на карте (
markerPosition). - Полный адрес объекта (
address). Некоторые компоненты адреса доступны только по запросу: см. описание объекта Address. - (Данные по запросу) Информация об этаже здания, на котором расположен объект (
levelIdиbuildingLevels). Актуально для компаний, которые расположены на определённом этаже многоэтажного здания. - (Данные по запросу) Информация о входах в объект (
entrances) с координатами и другими данными. Актуально как для компаний и зданий, так и для других объектов с физически обозначенными входами (например, парков). - (Данные по запросу) Дополнительная информация для уточнения адреса (
titleAddition). Например, номер подъезда или номер квартиры.
- Координаты для размещения маркера на карте (
-
Время работы:
- Смещение локального времени объекта от UTC в виде временной метки (
timeZoneOffset). Например,03:00:00для часового пояса UTC+3. - Время работы (
openingHours) в виде списка временных промежутков или флага круглосуточной работы. Актуально для компаний. - Текущий статус работы (
workStatus). Актуально для организаций.
- Смещение локального времени объекта от UTC в виде временной метки (
-
Прочие данные:
- (Данные по запросу) Информация о торговой лицензии организации (
tradeLicense). - Контакты для связи с организацией (
contactInfos): номер телефона, e-mail, ссылки на сайт и соцсети и другое. - Рейтинг объекта на основе отзывов пользователей (
reviews). - Дополнительные свойства парковок (
parkingInfo). - Дополнительные свойства электрозаправок (
chargingStation). - Информация о здании (
buildingInfo).
- (Данные по запросу) Информация о торговой лицензии организации (
Объединение объектов
Некоторые геообъекты в справочнике могут быть представлены в виде группы объектов разного типа. Например, здание суда — это одновременно и отдельно стоящее здание, и организация внутри этого здания, то есть два разных DirectoryObject с характеристиками здания и организации соответственно. Но поскольку эти DirectoryObject относятся к одному и тому же геообъекту, в их структуре данных содержатся ссылки друг на друга.
Информация о связанных объектах содержится в поле group в виде списка элементов GroupItem. Для каждого связанного объекта представлен его тип и идентификатор (DgisObjectId), который вы можете в дальнейшем использовать для обращения к этому объекту.
Доступ к данным в поле group предоставляется при дополнительной настройке ключа за отдельную плату. Чтобы обновить настройки вашего ключа доступа, обратитесь в службу поддержки 2ГИС.
Пример наполнения поля group с одним связанным объектом:
group: [
GroupItem(
id: DgisObjectId(objectId: 70030076538159915, entranceId: 0),
type: ObjectType.attraction,
),
],
Примеры
Ниже представлены примеры DirectoryObject разных типов объектов справочника.
-
Филиал организации:
DirectoryObject// Тип объекта — организация
types: [ObjectType.branch],
// Название организации
title: 'Шоколадница',
titleAddition: null,
// Подтип организации — кофейня
subtitle: 'Кофейня',
// ID объекта (данного филиала организации)
id: DgisObjectId(objectId: 4504128908451067, entranceId: 0),
// Координаты маркера для размещения на карте
markerPosition: GeoPointWithElevation(
latitude: Latitude(value: 55.7659),
longitude: Longitude(value: 37.602827),
elevation: Elevation(value: 18.0),
),
// Адрес организации — Москва, ул. Тверская 19а
address: Address(
drillDown: [
AddressAdmDiv(type: 'country', name: 'Россия'),
AddressAdmDiv(type: 'region', name: 'Москва'),
AddressAdmDiv(type: 'city', name: 'Москва'),
AddressAdmDiv(type: 'district', name: 'Тверской'),
],
components: [
AddressComponent(
AddressStreet(
street: 'Тверская улица',
number: '19а',
fiasCode: null,
),
),
],
buildingName: null,
buildingId: BuildingId(value: 4504235282747324),
postCode: '125009',
buildingCode: null,
fiasCode: null,
addressComment: '1-2 этаж',
),
attributes: [],
contextAttributes: [],
// Локальный часовой пояс — UTC+3
timeZoneOffset: Duration(hours: 3),
// Время работы филиала: понедельник-четверг с 7:00 до 23:00, пятница с 7:00 до 24:00,
// суббота — круглосуточно, воскресенье с 0:00 до 23:00
openingHours: OpeningHours(
weekOpeningHours: [
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.monday, time: DayTime(hours: 7, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.monday, time: DayTime(hours: 23, minutes: 0)),
),
],
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.tuesday, time: DayTime(hours: 7, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.tuesday, time: DayTime(hours: 23, minutes: 0)),
),
],
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.wednesday, time: DayTime(hours: 7, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.wednesday, time: DayTime(hours: 23, minutes: 0)),
),
],
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.thursday, time: DayTime(hours: 7, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.thursday, time: DayTime(hours: 23, minutes: 0)),
),
],
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.friday, time: DayTime(hours: 7, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.friday, time: DayTime(hours: 24, minutes: 0)),
),
],
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.saturday, time: DayTime(hours: 0, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.saturday, time: DayTime(hours: 24, minutes: 0)),
),
],
[
WeekTimeInterval(
startTime: WeekTime(weekDay: WeekDay.sunday, time: DayTime(hours: 0, minutes: 0)),
finishTime: WeekTime(weekDay: WeekDay.sunday, time: DayTime(hours: 23, minutes: 0)),
),
],
],
isOpen24x7: false,
),
contactInfos: [],
// Рейтинг 3.4 на основе 85 отзывов
reviews: Reviews(rating: 3.4, count: 85),
parkingInfo: null,
// В данный момент филиал открыт и работает до 23:00
workStatus: WorkStatus(
openStatus: OpenStatus.opened(Opened(null)),
openStatusHint: 'Открыто до 23:00',
scheduleHint: 'Сегодня до 23:00',
breakHint: null,
),
levelId: null,
buildingLevels: null,
// У организации один вход
entrances: [
EntranceInfo(
id: DgisObjectId(objectId: 4504128908451067, entranceId: 70030076156031010),
buildingNumber: null,
porchName: null,
porchNumber: null,
apartmentRanges: [],
geometry: EntranceGeometry(
entrancePoints: [
GeoPoint(
latitude: Latitude(value: 55.76590646318491),
longitude: Longitude(value: 37.60283837242394),
),
],
entrancePolylines: [
[
GeoPoint(
latitude: Latitude(value: 55.765971),
longitude: Longitude(value: 37.602949),
),
GeoPoint(
latitude: Latitude(value: 55.765906),
longitude: Longitude(value: 37.602838),
),
],
],
),
),
],
chargingStation: null,
// Объект относится к трём категориям
rubricIds: [
RubricId(value: 162),
RubricId(value: 1203),
RubricId(value: 161),
],
// Информация о головной организации и общем количестве филиалов
orgInfo: OrgInfo(
branchCount: 225,
id: OrgId(value: 4504136498310300),
name: 'Шоколадница, кофейня',
),
group: [], -
Жилое здание:
DirectoryObject// Тип объекта — здание
types: [ObjectType.building],
// Название объекта — адрес здания
title: '2-я Черногрязская улица, 1',
titleAddition: null,
// Подтип объекта — жилой дом
subtitle: 'Жилой дом',
// ID объекта
id: DgisObjectId(objectId: 4504235282792806, entranceId: 0),
// Координаты маркера для размещения на карте
markerPosition: GeoPointWithElevation(
latitude: Latitude(value: 55.760651),
longitude: Longitude(value: 37.545995),
elevation: Elevation(value: 3.0),
),
// Адрес объекта — Москва, 2-я Черногрязская улица 1
address: Address(
drillDown: [
AddressAdmDiv(type: 'country', name: 'Россия'),
AddressAdmDiv(type: 'region', name: 'Москва'),
AddressAdmDiv(type: 'city', name: 'Москва'),
AddressAdmDiv(type: 'district', name: 'Пресненский'),
],
components: [
AddressComponent(
AddressStreet(
street: '2-я Черногрязская улица',
number: '1',
fiasCode: '91e0431b-5721-40b9-8bf0-5eb5377063a8',
),
),
],
buildingName: null,
buildingId: BuildingId(value: 4504235282792806),
postCode: '123100',
buildingCode: null,
fiasCode: null,
addressComment: null,
),
attributes: [],
contextAttributes: [],
timeZoneOffset: null,
openingHours: null,
contactInfos: [],
// Нет отзывов об объекте для подсчёта рейтинга
reviews: Reviews(rating: 0.0, count: 0),
parkingInfo: null,
workStatus: null,
levelId: null,
buildingLevels: null,
// У жилого здания два входа
entrances: [
EntranceInfo(
id: DgisObjectId(objectId: 4504235282792806, entranceId: 4504643304435799),
buildingNumber: null,
porchName: null,
porchNumber: null,
apartmentRanges: [],
geometry: EntranceGeometry(
entrancePoints: [
GeoPoint(
latitude: Latitude(value: 55.76073452440514),
longitude: Longitude(value: 37.54591428882596),
),
],
entrancePolylines: [
[
GeoPoint(
latitude: Latitude(value: 55.760822),
longitude: Longitude(value: 37.545949),
),
GeoPoint(
latitude: Latitude(value: 55.760735),
longitude: Longitude(value: 37.545914),
),
],
],
),
),
EntranceInfo(
id: DgisObjectId(objectId: 4504235282792806, entranceId: 70030076156588095),
buildingNumber: null,
porchName: '1 подъезд',
porchNumber: 1,
apartmentRanges: [
ApartmentRange(start: 1, end: 80),
],
geometry: EntranceGeometry(
entrancePoints: [
GeoPoint(
latitude: Latitude(value: 55.7605167221199),
longitude: Longitude(value: 37.54581996572112),
),
],
entrancePolylines: [
[
GeoPoint(
latitude: Latitude(value: 55.760497),
longitude: Longitude(value: 37.545975),
),
GeoPoint(
latitude: Latitude(value: 55.760517),
longitude: Longitude(value: 37.54582),
),
],
],
),
),
],
chargingStation: null,
rubricIds: [],
orgInfo: null,
group: [], -
Улица:
DirectoryObject// Тип объекта — улица
types: [ObjectType.street],
// Название объекта
title: 'Улица Петрова',
titleAddition: null,
// Подтип объекта — улица
subtitle: 'Street',
// ID объекта
id: DgisObjectId(objectId: 4504338361766218, entranceId: 0),
// Координаты маркера для размещения на карте
markerPosition: GeoPointWithElevation(
latitude: Latitude(value: 55.643536),
longitude: Longitude(value: 38.053038),
elevation: Elevation(value: 0.0),
),
// Адрес объекта — Московская область, пгт Удельная
address: Address(
drillDown: [
AddressAdmDiv(type: 'country', name: 'Россия'),
AddressAdmDiv(type: 'region', name: 'Московская область'),
AddressAdmDiv(type: 'district_area', name: 'Раменский муниципальный округ'),
AddressAdmDiv(type: 'settlement', name: 'пгт Удельная'),
],
components: [],
buildingName: null,
buildingId: null,
postCode: null,
buildingCode: null,
fiasCode: '0d8e2b4c-eef7-4176-bbec-be9ac0ace587',
addressComment: null,
),
attributes: [],
contextAttributes: [],
timeZoneOffset: null,
openingHours: null,
contactInfos: [],
reviews: null,
parkingInfo: null,
workStatus: null,
levelId: null,
buildingLevels: null,
entrances: [],
chargingStation: null,
rubricIds: [],
orgInfo: null,
group: [], -
Площадной объект (парк):
DirectoryObject// Основной тип объекта — площадной объект, дополнительный — достопримечательность
types: [ObjectType.admDivPlace, ObjectType.attraction],
// Название объекта
title: 'Парк "Красногвардейские пруды"',
titleAddition: null,
// Подтип объекта — место
subtitle: 'Место',
// ID объекта
id: DgisObjectId(objectId: 4504286822138295, entranceId: 0),
// Координаты маркера для размещения на карте
markerPosition: GeoPointWithElevation(
latitude: Latitude(value: 55.756656),
longitude: Longitude(value: 37.545756),
elevation: Elevation(value: 0.0),
),
// Адрес объекта — Москва
address: Address(
drillDown: [
AddressAdmDiv(type: 'country', name: 'Россия'),
AddressAdmDiv(type: 'region', name: 'Москва'),
AddressAdmDiv(type: 'city', name: 'Москва'),
],
components: [],
buildingName: null,
buildingId: null,
postCode: null,
buildingCode: null,
fiasCode: null,
addressComment: null,
),
attributes: [],
contextAttributes: [],
timeZoneOffset: null,
openingHours: null,
contactInfos: [],
// Рейтинг 4.8 на основе 62 отзывов
reviews: Reviews(rating: 4.8, count: 62),
parkingInfo: null,
workStatus: null,
levelId: null,
buildingLevels: null,
entrances: [],
chargingStation: null,
// Объект относится к одной категории
rubricIds: [RubricId(value: 168)],
orgInfo: null,
// Объект одновременно является и площадным объектом, и достопримечательностью
group: [
GroupItem(
id: DgisObjectId(objectId: 70030076538159915, entranceId: 0),
type: ObjectType.attraction,
),
],
Поисковые подсказки
Вы можете формировать подсказки для пользователей при текстовом поиске объектов. Для этого создайте объект SuggestQuery с помощью SuggestQueryBuilder и передайте его в метод suggest():
import {
SuggestHandlerKind,
SuggestQueryBuilder,
} from '@2gis/dgis-mobile-sdk-full';
const suggestQuery = SuggestQueryBuilder.fromQueryText('коф')
.setAreaOfInterest(map.camera.visibleRect)
.build();
const future = searchManager.suggest(suggestQuery);
future.onComplete(
result => {
result.suggests.forEach(suggest => {
switch (suggest.handler.kind) {
case SuggestHandlerKind.ObjectHandler:
console.log('Object:', suggest.handler.value.item.title);
break;
case SuggestHandlerKind.IncompleteTextHandler:
console.log('Complete:', suggest.handler.value.queryText);
break;
case SuggestHandlerKind.PerformSearchHandler: {
const searchFuture = searchManager.search(
suggest.handler.value.searchQuery,
);
searchFuture.onComplete(
searchResult => {
console.log(searchResult.firstPage?.items ?? []);
searchFuture.destroy();
},
error => {
console.warn(error);
},
);
break;
}
}
});
future.destroy();
},
error => {
console.warn(error);
},
);
Вызов вернёт отложенный результат SuggestResult, содержащий список подсказок (Suggest). Подробнее о формировании подсказок см. в документации Suggest API.
Когда пользователь выбирает одну из предложенных подсказок, вы можете настроить реакцию на это событие с помощью обработчика SuggestHandler одного из следующих типов:
- SuggestObjectHandler — возвращает объект справочника DirectoryObject.
- PerformSearchHandler — возвращает объект поискового запроса SearchQuery. Вы можете использовать этот объект для дальнейшего поиска: передайте его в метод SearchManager.search() или создайте на его основе новый SearchQuery с дополнительными параметрами с помощью метода fromQuery() (подробнее см. в разделе Изменение параметров поиска).
- IncompleteTextHandler — возвращает автоматически дополненный текст подсказки, который можно использовать для дальнейшего формирования поискового запроса с помощью метода setQueryText().
История поиска
Вы можете работать с историей поиска с помощью SearchHistory.
В истории поиска могут храниться элементы двух типов: объекты справочника (DirectoryObject) и поисковые запросы (SearchQueryWithInfo).
Получить экземпляр можно через SearchHistory.instance(context).
Добавление элементов в историю поиска
Вы можете добавлять элементы в историю поиска в виде объектов SearchHistoryItem по одному или списком. Порядок элементов в списке сохраняется при добавлении в историю.
-
Создайте
SearchHistoryItemиз объекта нужного типа:- Для поискового запроса используйте SearchQueryWithInfo. Помимо поискового запроса, объект может содержать заголовок и подзаголовок для отображения в истории.
- Для объекта справочника используйте DirectoryObject.
-
Получите экземпляр
SearchHistoryс помощью методаSearchHistory.instance(context). -
Добавьте подготовленные элементы методом
addItem()по одному или методомaddItems()списком.
import {
SearchHistory,
SearchHistoryItem,
SearchQueryWithInfo,
} from '@2gis/dgis-mobile-sdk-full';
const history = SearchHistory.instance(context);
history.addItem(SearchHistoryItem.directoryObject(directoryObject));
history.addItem(
SearchHistoryItem.searchQuery(
new SearchQueryWithInfo(textQuery, 'Кофейни', 'Рядом со мной'),
),
);
Чтобы добавить сразу несколько подготовленных элементов:
history.addItems(searchHistoryItems);
Если добавляемый элемент уже существует в истории, более старый дубликат будет удалён.
Отображение истории поиска
Чтобы показать страницу поиска со списком элементов, создайте объект SearchHistoryPage и передайте её в метод items(). Дополнительно вы можете настроить следующие параметры:
- Ограничить количество элементов на странице (параметр
limit). Значение по умолчанию — 100. - Задать смещение относительно начала списка (параметр
offset): сколько элементов с начала списка пропустить. Значение по умолчанию — 0 (смещение отсутствует, список отображается с самого начала). - Отфильтровать список по типу элементов (параметр
filter). Доступные фильтры перечислены в SearchHistoryFilter. Например, чтобы показывать в истории только поисковые запросы, используйте значениеsearchQuery. По умолчанию фильтрация отсутствует.
import { SearchHistoryPage } from '@2gis/dgis-mobile-sdk-full';
const future = history.items(new SearchHistoryPage({ limit: 20n }));
future.onComplete(
result => {
console.log(result.items);
future.destroy();
},
error => {
console.warn(error);
},
);
Элементы на странице упорядочены по времени добавления: от новых к старым.
Очистка истории поиска
Чтобы удалить отдельные элементы из истории поиска:
-
Чтобы удалить один элемент, передайте нужный
SearchHistoryItemв методremoveItem(). Подробнее о созданииSearchHistoryItemсм. в разделе Добавление элементов в историю поиска.history.removeItem(searchHistoryItem); -
Чтобы удалить несколько элементов, передайте список объектов
SearchHistoryItemв методremoveItems(). Подробнее о созданииSearchHistoryItemсм. в разделе Добавление элементов в историю поиска.history.removeItems(searchHistoryItems);
Чтобы полностью очистить историю поиска, вызовите метод clear():
history.clear();
Подписка на изменения истории
Чтобы отслеживать добавление и удаление элементов, подпишитесь на канал onHistoryChanged. Обработчик получает ChangeType, который указывает тип изменения: Add или Remove.
const connection = history.onHistoryChanged.subscribe(change => {
console.log('History changed:', change);
});
connection.disconnect();
Когда отслеживание больше не требуется, вызовите disconnect() у полученного объекта подключения.
Информация о подъездах в справочнике
Вы можете искать адреса в справочнике с точностью до квартиры или подъезда.
Например, по запросу "Томск Кирова 17 кв 5" вы получите объект, который содержит информацию с точностью до подъезда.
DgisObjectId содержит два идентификатора:
objectId— стабильный числовой идентификатор объекта;entranceId— стабильный числовой идентификатор входа или подъезда объекта.
Если entranceId не равен 0n, результат поиска относится к конкретному подъезду здания.
Чтобы поставить маркер у найденного подъезда или получить его координаты для построения маршрута, не используйте markerPosition: это поле содержит позицию маркера самого здания. Найдите вход с соответствующим entranceId в поле entrances объекта DirectoryObject и используйте первую точку из geometry.entrancePoints. Если геометрия входа отсутствует, используйте координаты из markerPosition.
import { GeoPoint, type DirectoryObject } from '@2gis/dgis-mobile-sdk-full';
function getMarkerPosition(directoryObject: DirectoryObject): GeoPoint | null {
const entranceId = directoryObject.id?.entranceId ?? 0n;
if (entranceId === 0n) {
return null;
}
const entrance = directoryObject.entrances.find(
item => item.id.entranceId === entranceId,
);
const entrancePoint = entrance?.geometry?.entrancePoints[0];
if (entrancePoint !== undefined) {
return entrancePoint;
}
const markerPosition = directoryObject.markerPosition;
if (markerPosition === null) {
return null;
}
return new GeoPoint({
latitude: markerPosition.latitude,
longitude: markerPosition.longitude,
});
}