This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Retrieve a Building

 

This method is used to retrieve a building by building ID. A building can be retrieved such that the response also contains information about the floors it contains. This is done by passing the parameter "deep":true. Passing "deep":false requests only data about the building itself. The default behavior is "deep":true.

The latitude and longitude information is duplicated in the JSON payloads for backwards compatibility with v1.0. Using the "location" field for latitude and longitude values is preferred and takes precedence if there are any differences. Use of the previous latitude and longitude fields outside of a location object has been deprecated.

Method

GET

URL

http://map-api.phunware.com/v1.1/buildings/[id]

Headers

X-Auth (see Security)

Query Parameters

Required parameters are underlined.

Parameter

Value

Description

deep

Boolean

Information about a building can be retrieved along with floor details by passing true. Passing false requests only data about the building itself.

 Default value: true

draftStatusStringEither "LIVE" or "DRAFT". Defaults to "LIVE".

Example Query Fragment

Example with "deep" set to false:

{
	"deep": false
}  

Example with "deep" set to true:

{
	"deep": true
} 

URL-encoded, minified fragment for "deep" set to false:

7B%22deep%22%3Afalse%7D 

URL-encoded, minified fragment for "deep" set to true:

%7B%0A%22deep%22%3A+true%0A%7D

Example Request

Example with "deep" set to false:

http://map-api.phunware.com/v1.1/buildings/6891?7B%22deep%22%3Afalse%7D

Example with "deep" set to true:

http://map-api.phunware.com/v1.1/buildings/6891?%7B%0A%22deep%22%3A+true%0A%7D

Response

If "deep" is set to false, a successful response will have a 200 status code and a body containing an object with building data that does not contain information about the floors of the building:

{
    "id": <integer>,
    "name": <string>,
    "campusId": <integer>,
    "latitude": <float>,
    "longitude": <float>,
    "streetAddress": <string>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "floors": null"venueGuid": <string>,
    "location": 
	{
        "latitude": <float>,
        "longitude": <float>
    },
    "externalId": <integer>
} 

If "deep" is set to true, a successful response will have a 200 status code and a body containing an object with building data that contains information about its floors:

{
    "id": <integer>,
    "name": <string>,
    "campusId": <integer>,
    "latitude": <float>,
    "longitude": <float>,
    "streetAddress": <string>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "floors": 
	[
        {
            "id": <integer>,
            "name": <string>,
            "originalMapUrl": <string>,
            "buildingId": <integer>,
            "level": <integer>,
            "isOutdoor": <Boolean>,
            "width": <decimal>,
            "height": <decimal>,
            "offsetX": <integer>,
            "offsetY": <integer>,
            "locationMapHierarchy": <string>,
            "createdAt": <string>,
            "updatedAt": <string>,
            "buildingId": <integer>,
            "resources": 
			[
                {
                    "id": <integer>,
                    "buildingId": <integer>,
                    "floorId": <integer>,
                    "pdfUrl": <string>,
                    "svgUrl": <string>,
                    "zoomLevel": <integer>,
                    "createdAt": <string>,
                    "updatedAt": <string>
                }
            ],
            "venueGuid": <string>,
            "maxZoomLevel": <int>,
            "referencePoints": 
			{
                "rotation": <decimal>,
                "topLeft": 
				{
                    "latitude": <decimal>,
                    "longitude": <decimal>
                },
                "topRight": 
				{
                    "latitude": <decimal>,
                    "longitude": <decimal>
                },
                "bottomLeft": 
				{
                    "latitude": <decimal>,
                    "longitude": <decimal>
                },
                "bottomRight": 
				{
                    "latitude": <decimal>,
                    "longitude": <decimal>
                },
                "portal": 
				{
                    topRight":
					{
						"latitude": <decimal>,
						"longitude": <decimal>
					},
					"bottomLeft":
					{
						"latitude": <decimal>,
						"longitude": <decimal>
					}
				}
			}
		}
	],
	"venueGuid": <string>,
	"location": 
	{
		"latitude": <float>,
		"longitude": <float>
	},
    "externalId": <integer>
}  

See Mapping API Response Handling for error payloads.

Example Response

Example body of a successful response for "deep" set to false:

{
    "id": 2,
    "name": "Hyrule Castle Tower",
    "campusId": 6891,
    "latitude": 30.25,
    "longitude": 97.75,
    "streetAddress": "123 Ocarina",
    "createdAt": "2014-06-06T18:25:26Z",
    "updatedAt": "2014-06-06T18:25:33Z",
    "floors": null,
    "venueGuid": "03521872-2845-4024-896d-5fa0ab555c12",
    "location": 
	{
        "latitude": 30.25,
        "longitude": 97.75
    },
    "externalId": 2
}

Example body of a successful response for "deep" set to true:

{
    "id": 2,
    "campusId": 6891,
    "name": "Hyrule Castle Tower",
    "latitude": 30.25,
    "longitude": 97.75,
    "streetAddress": "123 Ocarina",
    "createdAt": "2014-07-10T14:56:49Z",
    "updatedAt": "2014-07-10T14:56:49Z",
    "floors": 
	[
        {
            "id": 17,
            "buildingId": 6891,
            "name": "Floor 1",
            "originalMapUrl": null,
            "isOutdoor": false,
            "level": 1,
            "width": 300.0,
            "height": 150.0,
            "offsetX": 0,
            "offsetY": 0,
            "locationMapHierarchy": "Hyrule>Hyrule Castle>Hyrule Castle Tower>Floor 1",
            "resources": 
			[
                {
                    "id": 5453,
                    "floorId": 4343,
                    "pdfUrl": "http://image.com/level1.pdf",
                    "svgUrl": "http://image.com/level1.svg",
                    "zoomLevel": 0,
                    "createdAt": "2002-10-02T10:00:00Z",
                    "updatedAt": "2002-10-02T10:00:00Z"
                }
            ],
            "venueGuid": "03521872-2845-4024-896d-5fa0ab555c12",
            "maxZoomLevel": 1,
            "referencePoints": 
			{
                "rotation": 0.0,
                "topLeft": 
				{
                    "latitude": 37.326617,
                    "longitude": -121.948756
                },
                "topRight": 
				{
                    "latitude": 37.326617,
                    "longitude": -121.942209
                },
                "bottomLeft": 
				{
                    "latitude": 37.324086,
                    "longitude": -121.948756
                },
                "bottomRight": 
				{
                    "latitude": 37.324086,
                    "longitude": -121.942209
                },
                "portal": 
				{
                    "topRight": 
					{
                        "latitude": 37.326617,
                        "longitude": -121.942209
                    },
                    "bottomLeft": 
					{
                        "latitude": 37.324086,
                        "longitude": -121.948756
                    }
                }
            }
        }
    ],
	"venueGuid": "03521872-2845-4024-896d-5fa0ab555c12",
    "location": 
	{
        "latitude": 30.25,
        "longitude": 97.75
    },
    "externalId": 2
}

ON THIS PAGE