Contornos e entradas de edifícios

Use a API Geocoding para receber contornos e entradas de edifícios e melhorar a visualização de dados nas renderizações de mapas.

Para isso, inclua um parâmetro adicional na sua solicitação de geocodificação para retornar pares de coordenadas de latitude/longitude que definem o contorno de um edifício ou uma entrada. Use a saída das suas solicitações para desenhar contornos de edifícios e indicar entradas no mapa.

• O contorno de um edifício é um conjunto de pares de coordenadas de latitude/longitude que definem um polígono 2D representando a área da superfície da Terra coberta pelo edifício.
• Uma entrada de edifício é um único par de coordenadas de latitude/longitude que define a localização de um ponto de entrada e saída de um lugar.

Uso e cobertura

É possível usar o serviço para retornar polígonos de contorno de um único lugar em uma única solicitação. Isso significa que uma solicitação de um geocódigo no nível da cidade, como Londres, Reino Unido, não retorna todos os contornos de edifícios nessa localidade. Nesses casos, o serviço retornaria uma resposta de geocodificação padrão sem contornos ou entradas de edifícios. Especificamente, o serviço gera contornos e entradas apenas para os seguintes tipos de lugar:

Tipos de lugares compatíveis

Embora esse recurso esteja disponível para uso em todas as regiões, a cobertura varia de acordo com a região. Além disso, você vai receber respostas da API que contêm um contorno do edifício, mas não dados de entrada. Nesse caso, o serviço vai retornar uma resposta de geocodificação com um contorno do edifício, mas sem uma matriz de dados de entrada. O serviço trabalha continuamente para melhorar a cobertura de entradas.

Detalhes da solicitação

É possível receber contornos de edifícios e coordenadas de entrada nos seguintes tipos de solicitações:

• Solicitação de geocodificação
• Solicitação de geocodificação inversa
• Fazer uma solicitação de geocodificação de lugar

Para qualquer uma dessas solicitações, forneça este parâmetro: extra_computations=BUILDING_AND_ENTRANCES.

Exemplo de solicitação

A consulta a seguir usa o geocoding de lugar para obter informações de entrada e contorno de um restaurante em Mountain View, Califórnia, Estados Unidos:

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

Exemplo de resposta

Na maioria dos casos, a resposta retorna um único edifício com as entradas conhecidas dele. Mas, em alguns casos, a resposta pode ter vários edifícios, como pontos de interesse que ocupam vários edifícios. Os edifícios e as entradas são representados com as duas matrizes a seguir:

Uma matriz buildings[] com um ou mais edifícios. Cada edifício contém os seguintes campos:

• place_id

  O identificador exclusivo do edifício. Consulte a visão geral dos IDs de lugar para mais detalhes.

• building_outlines[]

  Uma matriz de contornos associados ao edifício. Essa matriz tem apenas uma entrada. Cada objeto em building_outlines[] tem o seguinte campo:

  • display_polygon

  A codificação GeoJSON do polígono que se aproxima da área da superfície da Terra coberta pelo edifício, usando o formato RFC 7946.

Uma matriz entrances[] com os seguintes campos:

• location

  Coordenadas de latitude/longitude da entrada.

• building_place_id

  O ID do lugar do edifício em buildings[] que contém essa entrada. Isso permite identificar quais edifícios têm quais entradas. Essa entrada corresponde ao edifício no índice i em buildings[], em que buildings[i].place_id é igual ao building_place_id dessa entrada. Observação: esse valor é diferente do ID do lugar do resultado da geocodificação, a menos que o resultado seja para o próprio edifício. Esse parâmetro nem sempre é preenchido.

• entrance_tags[]

  Uma matriz de tags de entrada que descreve as características da entrada. O seguinte valor é compatível:

  • "PREFERRED"

    Indica que essa entrada provavelmente oferece acesso físico ao lugar retornado. Um lugar pode ter várias entradas preferenciais. Se uma entrada não tiver essa tag, significa que ela está fisicamente no mesmo prédio, mas não necessariamente dá acesso ao local.

    Por exemplo, se o lugar retornado for um restaurante em uma galeria, as entradas "PREFERRED" serão as que levam ao restaurante, enquanto as outras entradas retornadas serão outras entradas do edifício, como as de outros restaurantes na galeria.

    Se o lugar retornado for um prédio, as entradas "PREFERRED" serão as que levam à parte "principal" do prédio. Por exemplo, em um shopping center, as entradas "PREFERRED" são as que permitem acesso ao saguão principal. No entanto, se uma entrada só permitir acesso a uma loja na lateral do edifício, ela não será uma entrada "PREFERRED".

A imagem abaixo mostra uma representação visual do contorno do edifício e das entradas retornadas para a solicitação de exemplo acima.

A resposta da solicitação de exemplo acima mostra duas entradas e um único edifício com um contorno. O building_place_id de cada entrada corresponde ao place_id do prédio:

{
  "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"
    }
  ],
}

Mostrar contornos de edifícios em um mapa

A API JavaScript tem suporte integrado para mostrar polígonos e multipolígonos no formato RFC 7946. Faça o seguinte:

1. Crie um objeto de recurso usando os dados do polígono.
2. Aplique um estilo ao polígono.
3. Anexe o recurso ao objeto de mapa JavaScript.

Cada objeto na matriz buildings contém um único objeto na matriz building_outlines. O exemplo a seguir mostra como exibir o contorno de um prédio em um mapa:

//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)
    }
}

Usando o código acima, o contorno do edifício retornado pela API Geocoding na resposta de exemplo anterior neste documento é renderizado no mapa da seguinte maneira:

Processar respostas com vários edifícios ou contornos de edifícios

Você também pode encontrar as seguintes situações, mas o código de amostra acima ainda vai funcionar para elas:

1. Um único objeto building_outlines que representa vários polígonos.
2. Uma resposta com vários edifícios na matriz buildings[].

Por exemplo, a resposta para o ID do lugar ChIJGxgH9QBVHBYRl13JmZ0BFgo contém dois edifícios na matriz 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"
    }
]

Usando o exemplo de código JavaScript acima, podemos renderizar os dois contornos de edifícios no mapa:

Feedback

Este é um recurso experimental. Agradecemos seu feedback em [email protected].