Контуры зданий и входы

Используйте API геокодирования для получения контуров зданий и входов в них, что позволит улучшить визуализацию данных при визуализации карт.

Для этого включите дополнительный параметр в запрос геокодирования, чтобы вернуть пары координат широты и долготы, которые определяют контур здания или вход. Используйте выходные данные запросов для отображения контуров зданий и обозначения входов на карте.

• Контур здания представляет собой набор пар координат широты и долготы, которые определяют двухмерный многоугольник, представляющий площадь поверхности Земли, занимаемую зданием.
• Вход в здание — это одна пара координат широты/долготы, которая определяет местоположение точки входа и выхода в определенное место.

Использование и покрытие

Вы можете использовать сервис для возврата контурных полигонов для одного места в одном запросе. Это означает, что запрос на геокодирование на уровне города, например, Лондона, Великобритания, не возвращает контуры всех зданий в пределах этого населённого пункта. В таких случаях сервис вернёт стандартный ответ геокодирования без контуров зданий и входов. В частности, сервис генерирует контуры и входы только для следующих типов мест:

Поддерживаемые типы мест

Хотя эта функция доступна во всех регионах, покрытие варьируется в зависимости от региона. Более того, следует ожидать получения ответов API, содержащих контур здания, но не содержащих данные о входе. В этом случае сервис вернёт ответ геокодирования с контуром здания, но без массива данных о входе. Сервис постоянно работает над улучшением покрытия входов.

Запросить подробности

Получить контуры здания и координаты входа можно по следующим видам запросов:

• Запрос геокодирования
• Запрос обратного геокодирования
• Разместить запрос геокодирования

Для любого из этих запросов вы указываете этот параметр: extra_computations=BUILDING_AND_ENTRANCES .

Пример запроса

Следующий запрос использует геокодирование места для получения информации о входе и плане ресторана в Маунтин-Вью, Калифорния, США:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJl2tj2-62j4ARzKWl1WCXLJI&extra_computations=BUILDING_AND_ENTRANCES&key=YOUR_API_KEY

Пример ответа

В большинстве случаев ответ возвращает одно здание вместе с известными входами в него. Но в некоторых случаях ответ может содержать несколько зданий, например, объекты интереса, занимающие несколько зданий. Здания и входы представлены следующими двумя массивами:

Массив buildings[] с одним или несколькими зданиями. Каждое здание содержит следующие поля:

• place_id

  Уникальный идентификатор здания. Подробнее см. в разделе «Обзор идентификаторов мест» .

• building_outlines[]

  Массив контуров, связанных со зданием. Этот массив содержит только один элемент. Каждый объект в building_outlines[] имеет следующее поле:

  • display_polygon

  GeoJSON-кодирование многоугольника, приблизительно соответствующего площади поверхности Земли, занимаемой зданием, с использованием формата RFC 7946.

Массив entrances[] со следующими полями:

• location

  Координаты широты/долготы входа.

• building_place_id

  Идентификатор места здания в buildings[] , содержащего этот вход. Это позволяет определить, какие здания содержат какие входы. Этот вход соответствует зданию с индексом i в buildings[] , где buildings[i].place_id равен building_place_id этого входа. Примечание: это значение отличается от идентификатора места в результате геокодирования, если только результат геокодирования не относится к самому зданию. Этот параметр не всегда заполняется.

• entrance_tags[]

  Массив тегов входа, описывающий его характеристики. Поддерживаются следующие значения:

  • "PREFERRED"

    Указывает, что этот вход, вероятно, обеспечивает физический доступ к возвращаемому объекту. У объекта может быть несколько предпочтительных входов. Если у входа нет этого тега, это означает, что он физически находится в том же здании, но не обязательно обеспечивает доступ к объекту.

    Например, если возвращаемое место — ресторан в торговом центре, "PREFERRED" входами будут те, которые ведут в сам ресторан, в то время как другие возвращаемые входы будут другими входами в здание, например, входы в другие рестораны в торговом центре.

    Если возвращаемое место само по себе является зданием, "PREFERRED" входами будут те, которые ведут в «главную» часть здания. Например, в торговом центре "PREFERRED" входами будут те, которые ведут в главное фойе, но если вход ведёт только в магазин сбоку здания, он не будет "PREFERRED" .

На изображении ниже показано визуальное представление контура здания и входов, возвращенных для приведенного выше примера запроса.

В ответе на запрос из примера выше показаны два входа и одно здание с контуром. Обратите внимание, что building_place_id каждого входа совпадает с place_id здания:

{
  "entrances": [
    {
        "building_place_id" : "ChIJU1erIO-2j4ARzlavxpYBJr8",
        "location" :
        {
          "lat" : 37.3736684,
          "lng" : -122.0540469
        },
        "entrance_tags": ["PREFERRED"]
    },
    {
        "building_place_id" : "ChIJU1erIO-2j4ARzlavxpYBJr8",
        "location" :
        {
          "lat" : 37.3738239,
          "lng" : -122.0539773
        },
    }
  ],
  "buildings" : [
    {
      "building_outlines" : [
        {
          "display_polygon" : {
            "coordinates" : [
              [
                [
                  -122.054453349467,
                  37.3742345734776
                ],
                [
                  -122.054665964955,
                  37.3737591984554
                ],
                [
                  -122.054080317537,
                  37.3735936952922
                ],
                [
                  -122.053867527481,
                  37.374069124071
                ],
                [
                  -122.054453349467,
                  37.3742345734776
                ]
              ]
            ],
            "type" : "Polygon"
          }
        }
      ],
      "place_id" : "ChIJU1erIO-2j4ARzlavxpYBJr8"
    }
  ],
}

Отображать контуры зданий на карте

API JavaScript имеет встроенную поддержку отображения полигонов и мультиполигонов в формате RFC 7946. Это можно сделать следующим образом:

1. Постройте объект-объект, используя данные полигона.
2. Примените стиль к многоугольнику.
3. Прикрепите функцию к объекту карты JavaScript.

Каждый объект в массиве buildings содержит один объект в массиве building_outlines . В следующем примере показано, как отобразить контур здания на карте:

//This function takes an argument of 'buildings', which is the buildings[] array returned by the API.
async function displayBuildingOutline(buildings) {
    try {
        //Import the Google Maps Data library.
        const { Data } = await google.maps.importLibrary("maps")
        //Loop though the array of building outlines.
        buildings.forEach(building => {
            const features = []
            const buildingOutlines = building.building_outlines;
            //Add each building outline to a Feature object, and push this to an array of Features.
            buildingOutlines.forEach(buildingOutline => {
                const feature = {
                    type: "Feature",
                    properties: {},
                    geometry: buildingOutline.display_polygon
                }
                features.push(feature);
            });
            //Create a new Google Maps Data object, and apply styling.
            //We also assume the reference to the map on the page is named 'map'.
            //This applies the Data object to the map on the page.
            outlineLayer = new google.maps.Data({
                map,
                style: {
                    strokeColor: "#0085cc",
                    strokeOpacity: 1,
                    strokeWeight: 2,
                    fillColor: "#88d4fc",
                    fillOpacity: 0.5,
                },
            });
            //Add the array of Features created earlier to the Data object, as GeoJson.
            outlineLayer.addGeoJson({
                type: "FeatureCollection",
                features: features,
            });
        });
    } catch (e) {
        console.log('Building outlines failed. Error: ' + e)
    }
}

При использовании приведенного выше кода контур здания, возвращенный API геокодирования в примере ответа, приведенном ранее в этом документе, отображается на карте следующим образом:

Обрабатывайте ответы с несколькими зданиями или контурами зданий

Вы также можете столкнуться со следующими ситуациями; однако приведенный выше пример кода будет работать и в этом случае:

1. Один объект building_outlines представляющий несколько полигонов.
2. Ответ с несколькими зданиями в массиве buildings[] .

Например, ответ для идентификатора места ChIJGxgH9QBVHBYRl13JmZ0BFgo содержит два здания в массиве buildings[] :

"buildings": [
    {
        "building_outlines": [
            {
                "display_polygon": {
                    "coordinates": [
                        [
                            [
                                44.3313253363354,
                                13.636033631612
                            ],
                            [
                                44.3312576355624,
                                13.6362094887862
                            ],
                            [
                                44.3310854239923,
                                13.6361461767801
                            ],
                            [
                                44.3311531250111,
                                13.6359703194634
                            ],
                            [
                                44.3313253363354,
                                13.636033631612
                            ]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        ],
        "place_id": "ChIJ24NWUBhUHBYRSEmPBFa1wgc"
    },
    {
        "building_outlines": [
            {
                "display_polygon": {
                    "coordinates": [
                        [
                            [
                                44.330737534504,
                                13.6357057440832
                            ],
                            [
                                44.3307248314371,
                                13.6357390350529
                            ],
                            [
                                44.3306985591742,
                                13.635729486373
                            ],
                            [
                                44.3307114066013,
                                13.6356960265536
                            ],
                            [
                                44.330737534504,
                                13.6357057440832
                            ]
                        ]
                    ],
                    "type": "Polygon"
                }
            }
        ],
        "place_id": "ChIJpzQOABlUHBYRxiOC9goY1fE"
    }
]

Используя приведенный выше пример кода JavaScript, мы можем отобразить на карте контуры обоих зданий:

Обратная связь

Это экспериментальная функция. Мы будем благодарны за ваши отзывы, отправленные по адресу geocoding-feedback-channel@google.com .