Use the Geocoding API to get building outlines and entrances to enhance data visualization in your map renderings.
To do this, include an additional parameter in your Geocoding request to return latitude/longitude coordinate pairs that either define a building outline, or an entrance. Use the output of your requests to draw building outlines and indicate building entrances on your map.
- A building outline is a set of latitude/longitude coordinate pairs that define a 2D polygon representing the surface area of the earth covered by the building.
- A building entrance is a single latitude/longitude coordinate pair that defines the location of an entry and exit point into a place.
Usage & coverage
You can use the service to return outline polygons for a single place in a single request. This means that a request for a city-level geocode, such as London, UK, does not return all building outlines within that locality. In such cases, the service would return a standard geocoding response with no building outlines or entrances. Specifically, the service generates outlines and entrances only for the following place types:
Supported place types
Building |
Entrances |
|---|---|
|
|
|
|
|
|
|
While this feature is available to use in all regions, coverage varies by region. Furthermore, you should expect to receive API responses that contain a building outline, but no entrance data. In this case, the service will return a geocoding response with a building outline, but no entrance data array. The service continually works to improve entrance coverage.
Request details
You can obtain building outlines and entrance coordinates in the following kinds of requests:
For any of these requests, you supply this parameter:
extra_computations=BUILDING_AND_ENTRANCES.
Example request
The following query uses place geocoding to obtain entrance and outline information for a restaurant in Mountain View, California, United States:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJ4TTDdzS3j4AR78EQgu5EADA&extra_computations=BUILDING_AND_ENTRANCES&key=YOUR_API_KEY
Example response
In most cases, the response returns fields that correspond to a single building, but in some cases, the response can have multiple elements, such as points of interest that occupy multiple buildings. The response elements include two arrays:
A buildings[] array with the following fields:
place_idThe unique identifier of the building. See the Place IDs overview for more details.
building_outlines[]An array of outlines associated with the building. This array has only one entry. Each object in
building_outlines[]has the following field:display_polygon
The GeoJSON encoding of the polygon that approximates the surface area of the earth covered by the building, using the RFC 7946 format
An entrances[] array with the following fields:
locationLatitude/longitude coordinates of the entrance.
building_place_idThe place ID of the building that contains the entrance. This is different from the place ID of the geocode result, unless the geocode result is for the building itself. This parameter won't always be populated.
The response from the query above shows one entrance and a single polygon item in the buildings array:
{
"entrances": [
{
"location": {
"lat": 37.3925065,
"lng": -122.0799465
},
"building_place_id": "ChIJVeHddzS3j4ARFZJVu4Cf27o"
}
],
"buildings" : [
{
"building_outlines" : [
{
"display_polygon" : {
"coordinates" : [
[
[
-122.080188246116,
37.3926407183216
],
[
-122.080281351765,
37.3924887558601
],
[
-122.080023707261,
37.392390122414
],
[
-122.079926266852,
37.3925369491992
],
[
-122.080188246116,
37.3926407183216
]
]
],
"type" : "Polygon"
}
}
],
"place_id" : "ChIJVeHddzS3j4ARFZJVu4Cf27o"
}
],
}
Display building outlines on a map
The JavaScript API has built-in support for displaying RFC 7946 format Polygons and MultiPolygons . You do this as follows:
- Build a feature object using the polygon data.
- Apply a style to the polygon.
- Attach the feature to the JavaScript map object.
Every object in the buildings array contains a single object in the
building_outlines array. The following example shows how to display a building
outline on a map:
//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)
}
}
Using the code above, the building outline returned by the Geocoding API within the example response earlier in this document is rendered on the map as follows:
Edge cases
You might also encounter the following edge cases; however, the above sample code will still work for these:
- A response with multiple building outlines.
- A single
building_outlinesobject representing multiple polygons.
For example, the response for the place ID ChIJGxgH9QBVHBYRl13JmZ0BFgo
contains two building_outlines[] array results:
"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"
}
]
Using the JavaScript code sample above, we are able to render both outlines on the map:
Feedback
This is an experimental feature. We would appreciate feedback at buildings-in-geocoding-feedback-channel@google.com.