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

Разработчики из Европейской экономической зоны (ЕЭЗ)

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

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

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

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

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

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

Здание

Входы

premise

premise

subpremise

subpremise

point_of_interest

point_of_interest

street_address

Хотя эта функция доступна во всех регионах, охват может различаться в зависимости от региона. Кроме того, вы можете ожидать получения ответов 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 .