Как использовать Places API и геокодирование с настройкой стилей на основе данных для границ

Если вы используете Places API или Geocoding API с Maps JavaScript API, то можете искать регионы и получать дополнительную информацию о местах. Эта удобная и надежная альтернатива поиску по идентификаторам мест. Если вы уже используете такие идентификаторы, то сможете легко применять их вместе со стилями на основе данных для границ.

Возможны следующие варианты использования Places и Geocoding в приложениях с Maps JavaScript API:

Поиск мест с помощью библиотеки Places и Maps JavaScript API (также поддерживают виджет автозаполнения).
Возврат информации о местах по HTTP-запросам с помощью Places API.
Динамическое геокодирование (в том числе обратное) вводимых данных с помощью сервиса Geocoding и класса Geocoder.
Геокодирование известных статических адресов с помощью Geocoding API.

Places API

Использование Text Search (предварительной версии) для поиска региона

Вы можете использовать Text Search (предварительную версию), чтобы получить идентификатор места с данными о регионе. Для этого в параметр includedType укажите нужный тип региона. Запрашивать идентификаторы мест с помощью API Text Search (предварительной версии) можно бесплатно. Подробнее…

В этом примере функция выполняет запрос searchByText, чтобы получить идентификатор места для "Trinidad, CA", а затем применяет стили к границам:

async function findBoundary(Place) {
    const request = {
        query: 'Trinidad, CA',
        fields: ['id', 'location'],
        includedType: 'locality',
        locationBias: center,
    };

    const { places } = await Place.searchByText(request);

    if (places.length) {
        const place = places[0];
        styleBoundary(place.id);
        map.setCenter(place.location);
    } else {
        console.log('No results');
    }
}

function styleBoundary(placeid) {
    // Define a style of transparent purple with opaque stroke.
    const styleFill = /** @type {!google.maps.FeatureStyleOptions} */({
        strokeColor: '#810FCB',
        strokeOpacity: 1.0,
        strokeWeight: 3.0,
        fillColor: '#810FCB',
        fillOpacity: 0.5
    });

    // Define the feature style function.
    featureLayer.style = (params) => {
        if (params.feature.placeId == placeid) {
            return styleFill;
        }
    };
}

initMap();

Использование автозаполнения мест для поиска регионов

С виджетом Places Autocomplete вашим пользователям будет удобно искать районы на карте. Если вы хотите, чтобы виджет возвращал только названия регионов, присвойте параметру types значение (regions), как показано в примере кода ниже:

// Set up the Autocomplete widget to return only region results.
const autocompleteOptions = {
  fields: ["place_id", "type"],
  strictBounds: false,
  types: ["(regions)"],
};

Получение информации о регионе

Вы можете запрашивать разную полезную информацию о регионе, например:

идентификаторы граничащих с регионом мест по его названию;
область просмотра для увеличения масштаба до границ региона;
объекты определенного типа внутри границ (например, locality);
форматированный адрес региона США в формате "населенный пункт, штат, страна" (например, "Оттумва, Айова, США");
фотографии и многое другое.

В примере ниже функция вызывает метод fetchFields(), чтобы получить сведения о места, в том числе place.geometry.viewport, а затем вызывает метод map.fitBounds(), чтобы центрировать карту по границам выбранного полигона.

async function getPlaceDetails(placeId) {
    // Use place ID to create a new Place instance.
    const place = new google.maps.places.Place({
        id: placeId,
    });

    // Call fetchFields, passing the desired data fields.
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'geometry', 'type'] });

    // Zoom to the boundary polygon.
    let viewport = place.geometry.viewport;
    map.fitBounds(viewport, 155);

    // Print some place details to the console.
    const types = place.types;
    console.log("Feature type: " + types[0]);
    console.log("Formatted address: " + place.formattedAddress);
}

Geocoding API

С помощью Geocoding API вы можете преобразовывать адреса в географические координаты и наоборот. Перечисленные ниже варианты использования хорошо сочетаются со стилями на основе данных для границ.

Получение области просмотра региона.
Фильтрация по компонентам в вызовах Geocoding – это позволяет получать идентификаторы мест для административных районов уровней 1–4, названий населенных пунктов и индексов.
Обратное геокодирование – это позволяет получать идентификаторы мест по географическим координатам, а также получать идентификаторы мест для всех компонентов в том или ином местоположении.

Получение области просмотра для региона

Сервис Geocoding позволяет получить область просмотра по идентификатору места, а затем передать ее функции map.fitBounds(), чтобы увеличить масштаб карты до граничного многоугольника. Пример ниже иллюстрирует получение области просмотра с помощью сервиса Geocoding и вызов функции map.fitBounds().

// Set up the geocoder.
geocoder = new google.maps.Geocoder();

...

// Call Geocoding API and zoom to the resulting bounds.
function zoomToPolygon(placeid) {
    geocoder
        .geocode({ placeId: placeid })
        .then(({ results }) => {
            map.fitBounds(results[0].geometry.viewport, 155);
        })
        .catch((e) => {
            console.log('Geocoder failed due to: ' + e)
        });
}

Обратное геокодирование

Обратное геокодирование позволяет получать идентификаторы мест. В примере ниже функция сервиса Geocoding возвращает идентификаторы места для всех компонентов адреса в точке с заданными координатами.

// Set up the geocoder.
geocoder = new google.maps.Geocoder();

...

// Call Geocoding API.
function getPlaceIds(latLng) {
    geocoder
        .geocode({ latLng })
        .then(({ results }) => {
            console.log('Geocoding result:');
            console.log(results[0]);
            console.log(results[0].place_id);
            console.log(results[0].address_components);
        })
        .catch((e) => {
            console.log('Geocoder failed due to: ' + e)
        });
}

Эта операция эквивалентна вызову веб-сервиса обратного геокодирования:

https://maps.googleapis.com/maps/api/geocode/json?key="YOUR_API_KEY"&latlng=41.864182,-87.676930

Обратное геокодирование можно использовать с фильтром компонентов адреса, чтобы получать только нужные вам компоненты:

administrativeArea
country
locality
postalCode

В примере ниже показано, как добавить ограничение при использовании функции обратного геокодирования в сервисе Geocoding, чтобы получить для заданной точки только адресный компонент locality:

// Set up the geocoder.
geocoder = new google.maps.Geocoder();

...

function getPlaceIdWithRestrictions(latLng) {
    geocoder
        .geocode({ latLng,
            componentRestrictions: {
              country: "US",
              locality: "chicago",
            },
        })
        .then(({ results }) => {
            console.log('Geocoding result with restriction:');
            console.log(results[0]);
            console.log(results[0].place_id);
            console.log(results[0].address_components);
            console.log(results[0].address_components[1].types[0]);
            console.log(results[0].address_components[1].long_name);
        })
        .catch((e) => {
            console.log('getPlaceId Geocoder failed due to: ' + e)
        });
}

Эта операция эквивалентна вызову веб-сервиса обратного геокодирования:

https://maps.googleapis.com/maps/api/geocode/json?key="YOUR_API_KEY"&latlng=41.864182,-87.676930&result_type=locality