AI-generated Key Takeaways

outlined_flag

• Enhance map visualizations with building outlines and entrances using the Geocoding API by including theextra_computations=BUILDING_AND_ENTRANCES parameter in requests.

• Building outlines are sets of latitude/longitude coordinates defining a building's footprint, while entrances are single coordinate pairs marking entry/exit points.

• The feature supports specific place types likepremise,subpremise,point_of_interest, andstreet_address, with varying coverage and ongoing entrance data improvements.

• The Geocoding API response includesbuildings[] andentrances[] arrays containing outline polygons and entrance locations, respectively.

• Utilize the JavaScript API to display building outlines on a map by constructing feature objects from polygon data and applying them to the map.

This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by theGoogle Maps Platform Service Specific Terms. For more information, see thelaunch stage descriptions.

Use the Geocoding API to get building outlines and entrances to enhance datavisualization in your map renderings.

To do this, include an additional parameter in your Geocoding request to returnlatitude/longitude coordinate pairs that either define a building outline, or anentrance. Use the output of your requests to draw building outlines and indicatebuilding entrances on your map.

• A building outline is aset of latitude/longitude coordinate pairsthat define a 2D polygon representing the surface area of the earth coveredby the building.
• A building entrance is asingle latitude/longitude coordinate pairthat defines the location of an entry and exit point into a place.

Usage & coverage

You can use the service to return outline polygons for asingle place in asingle request. This means that a request for a city-level geocode, such asLondon, UK, does not return all building outlines within that locality. In suchcases, the service would return a standard geocoding response with no buildingoutlines or entrances. Specifically, the service generates outlines andentrances only for the following place types:

Supported place types

While this feature is available to use in all regions, coverage variesby region. Furthermore, you should expect to receive API responses that containa building outline, but no entrance data. In this case, the service will returna geocoding response with a building outline, but no entrance data array. Theservice continually works to improve entrance coverage.

Request details

You can obtain building outlines and entrance coordinates in the following kindsof requests:

• Geocoding request
• Reverse geocoding request
• Place geocoding request

For any of these requests, you supply this parameter:extra_computations=BUILDING_AND_ENTRANCES.

Example request

The following query usesplacegeocoding to obtainentrance and outline information for a restaurant in Mountain View, California,United States:

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

Example response

In most cases, the response returns a single building along with the knownentrances of the building. But in some cases, the response can have multiplebuildings, such as points of interest that occupy multiple buildings. Thebuildings and entrances are represented with the following two arrays:

Abuildings[] array with one or more buildings. Each building contains thefollowing fields:

• place_id

  The unique identifier of the building. See thePlace IDsoverview for more details.

• building_outlines[]

  An array of outlines associated with the building. This array has only oneentry. Each object inbuilding_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 theRFC 7946 format

• location

  Latitude/longitude coordinates of the entrance.

• building_place_id

  The place ID of the building inbuildings[] that contains this entrance.This lets you identify which buildings contain which entrances.This entrance corresponds to the building at indexi inbuildings[]wherebuildings[i].place_id equals this entrance'sbuilding_place_id.Note: This value is different from the place ID of the geocode result,unless the geocode result is for the building itself. This parameter won'talways be populated.

• entrance_tags[]

  An array of entrance tags that describes characteristics of the entrance.The following value is supported:

  • "PREFERRED"

    Indicates this entrance likely provides physical access tothe returned place. A place can have multiple preferred entrances. If anentrance does not have this tag, it means the entrance is physically onthe same building but does not necessarily provide access to the place.

    For example, if the returned place is a restaurant in a strip mall, the"PREFERRED" entrances will be the ones that lead into the restaurantitself, while the other returned entrances will be other entrances forthe building, such as entrances into other restaurants in the stripmall.

    If the returned place is a building itself, the"PREFERRED" entranceswill be the ones that lead into the "main" part of the building. Forexample, in a shopping center the"PREFERRED" entrances will be theones that allow access to the main foyer area, but if an entrance onlyprovides access to a store on the side of the building, it won't be a"PREFERRED" entrance.

    Note: A"PREFERRED" entrance might not provide access to the returnedplace, and a non-preferred might provide access to the returned place.

The image below shows a visual representation of the building outline andentrances returned for the example request above.

The response from the example request above shows two entrances and a singlebuilding with an outline. Notice that thebuilding_place_id of each entrancematches theplace_id of the building:

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

TheJavaScript API has built-insupport for displayingRFC 7946 format Polygons andMultiPolygons . You do this as follows:

1. Build a feature object using the polygon data.
2. Apply a style to the polygon.
3. Attach the feature to the JavaScript map object.

Every object in thebuildings array contains a single object in thebuilding_outlines array. The following example shows how to display a buildingoutline on a map:

//This function takes an argument of 'buildings', which is the buildings[] array returned by the API.asyncfunctiondisplayBuildingOutline(buildings){try{//Import the Google Maps Data library.const{Data}=awaitgoogle.maps.importLibrary("maps")//Loop though the array of building outlines.buildings.forEach(building=>{constfeatures=[]constbuildingOutlines=building.building_outlines;//Add each building outline to a Feature object, and push this to an array of Features.buildingOutlines.forEach(buildingOutline=>{constfeature={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=newgoogle.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 withinthe example response earlier in this document is rendered on the map as follows:

Handle responses with multiple buildings or building outlines

You might also encounter the following situations; however, the above samplecode will still work for these:

1. A singlebuilding_outlines object representing multiple polygons.
2. A response with multiple buildings in thebuildings[] array.

For example, the response for the place IDChIJGxgH9QBVHBYRl13JmZ0BFgocontains two buildings in thebuildings[] array:

"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 buildingoutlines on the map:

Feedback

This is an experimental feature. We would appreciate feedback atgeocoding-feedback-channel@google.com.