Place Management

Sites

Create Site

Sites are the highest level of the place hierarchy, representing the overview of a geographical area, containing one or more buildings. To create a new site for your org:

Request Response
Copy
1
2
3
4
5
6
7
8
mutation {
	createSite(input: { site: { name: "Site Name" } }) {
		site {
			id
			name
		}
	}
}

Update Site

If you need to make any changes to an existing site, you would use updateSite - currently the only available field you can change for a site will be the name:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
mutation {
	updateSite(
		input: {
			site: { id: "SITENxx8N7WX5SZLBGysBNAbCd", name: "Site Name Update" }
		}
	) {
		site {
			name
		}
	}
}

Delete Site

To delete a site, you'll just call deleteSite and include the ID; note this is irreversible, so triple check you have the right ID before moving forward. We have to include something in the return fields, so we'll select the underscore. As long as you get a 200 OK and a JSON response back, the deletion should be successful.

Request Response
Copy
1
2
3
4
5
6
7
mutation {
	deleteSite(input: {
		id: "SITENxx8N7WX5SZLBGysBNAbCd"
	}) {
		_
	}
}

Buildings

Create Building

Buildings need to be part of a Site, so if you don't have a Site yet, go ahead and add one of those first. You'll need the siteId, so best to have that retrieved at this point as well. Otherwise, the createBuilding is only a little more complicated than creating a site - primarily because you need the building's address information. As we provide services to countries worldwide, our address fields are labeled with the intent to be as regionally agnostic as possible - they break down like this:

• streetAddress - This covers the remainder of the address - the building number and the street name, at minimum
• locality - this typically aligns with the city/town/village where the building is located, like "Redmond", "Seoul" or "Perth"
• region - This will typically align with a state or province, which again is not necessarily something present in all countries, such as "Washington" or "Western Australia".
• postalCode - not all countries utilize a post code (known as a ZIP code in the United States), so if the building doesn't have one, you can just leave it blank.
• countryName - pretty straightforward, the name of the country where the building is located like "United States", "South Korea", Australia".

Here's an example showing how to create a building:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
mutation {
	createBuilding(
		input: {
			building: {
				name: "Stark Tower"
				address: {
					countryName: "USA"
					streetAddress: "200 Park Ave"
					locality: "New York City"
					region: "New York"
					postalCode: "10166"
				}
				siteId: "SITENxx8N7WX5SZLBGysBNAbCd"
			}
		}
	) {
		building {
			id
			name
		}
	}
}

Update Building

If you wanted to update something about the building, such as the name or address, you would use updateBuilding. The syntax is very similar to updating a site, you just have more you can work with when updating a building. Note that you do not need to include all the fields to update one - i.e. you don't need to include the address if you want to update just the name.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
mutation {
	updateBuilding(
		input: {
			building: { id: "BLDG2w3qJHY77APFPuzSpAAbCd", name: "Oscorp Tower" }
		}
	) {
		building {
			name
		}
	}
}

Delete Building

To delete a building, you'll just call deleteBuilding and include the ID; note this is irreversible, so triple check you have the right ID before moving forward. We have to include something in the return fields, so we'll select the underscore. As long as you get a 200 OK and a JSON response back, the deletion should be successful.

Request Response
Copy
1
2
3
4
5
mutation {
	deleteBuilding(input: { id: "BLDG2w3qJHY77APFPuzSpAAbCd" }) {
		_
	}
}

Floors

Create Floor

After creating a building, you will need to add Floors to it. Floors add a layer of complexity, as you will need GeoJSON coordinates included in order to create the shape of your building. Typically each floor will have the same coordinates, although in the case of larger buildings like skyscrapers, the top floors may have varied dimensions.

Here's the syntax to add a floor with coordinates generated using the geojson.io browser tool; other methods are available, typically programmatically. Note the parameter level - you'll want to include that value to determine which floor you're creating. We use the international standard, which defines the "first floor" as level: 0, essentially the ground floor. Each floor from there will be 1, 2, 3 and so on:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
mutation {
	createFloor(
		input: {
			floor: {
				name: "Ground Floor"
				buildingId: "BLDG2w3qJHY77APFPuzSpAAbCd"
				level: 0
				geoshape: {
					type: "Polygon"
					coordinates: [
						[
							[-73.97800, 40.75259]
							[-73.97704, 40.75217]
							[-73.97587, 40.75376]
							[-73.97680, 40.75414]
							[-73.97800, 40.75259]
						]
					]
				}
			}
		}
	) {
		floor {
			id
			name
			geoshape
		}
	}
}

Update Floor

If you wanted to update something about the floor, such as the name, level or geoshape, you would use updateFloor. The syntax is very similar to creating a floor, or updating a site/building - note there are two possible IDs to include, the buildingId and just id. The latter represents the ID of the floor itself, and is required. Also note that you do not need to include all the fields to update one - i.e. you don't need to include the level if you want to update just the name of the floor.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation {
	updateFloor(
		input: {
			floor: {
				name: "First Floor"
				buildingId: "BLDGMkpsn2NJ75X99tFX4nAbCd"
				id: "FLRNQsSkiMZeTfeVwPmNBAbCd"
			}
		}
	) {
		floor {
			id
			name
		}
	}
}

Delete Floor

To delete a floor, you'll just call deleteFloor and include the ID; note this is irreversible, so triple check you have the right ID before moving forward. We have to include something in the return fields, so we'll select the underscore. As long as you get a 200 OK and a JSON response back, the deletion should be successful.

Request Response
Copy
1
2
3
4
5
mutation {
	deleteFloor(input: { id: "FLRNQsSkiMZeTfeVwPmNBAbCd" }) {
		_
	}
}

Spaces

Create Space

Spaces represent the individual rooms on a floor, like an office or a break room. To create a space, you'll make a call to createSpace with the necessary fields. You'll need a name, and will need to add the floorId where the space exists, and spaces will also need geoJSON data, like floors, as they need to be represented within the floor's geography.

Spaces also have a field called exactType. This field corresponds to the Brick Schema Location type for Space, and should be the one most refined / granular that represents how the space is used. You can go generic, like Room, but if you know the space is an Office, it's best to use that instead.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
mutation {
	createSpace(
		input: {
			space: {
				name: "Cafe"
				exactType: ["Room"]
				floorId: "FLRNQsSkiMZeTfeVwPmNBAbCd"
				geoshape: {
					type: "Polygon"
					coordinates: [
						[
							[-73.97626, 40.75391]
							[-73.97642, 40.75365]
							[-73.97624, 40.75359]
							[-73.97607, 40.75383]
							[-73.97626, 40.75391]
						]
					]
				}
			}
		}
	) {
		space {
			id
			name
			geoshape
		}
	}
}

Update Space

If you wanted to update something about the space, such as the name, exactType or geoshape, you would use updateSpace. The syntax is very similar to creating a space, or updating a floor - note there are two possible IDs to include, the floorId and just id. The latter represents the ID of the floor itself, and is required. Also note that you do not need to include all the fields to update one - i.e. you don't need to include the exactType if you want to update just the name of the space.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation {
	updateSpace(
		input: {
			space: {
				name: "Breakroom"
				floorId: "FLRNQsSkiMZeTfeVwPmNBAbCd"
				id: "SPCXWuZRuYs3YN12Syni3AbCd"
			}
		}
	) {
		space {
			id
			name
		}
	}
}

Delete Spaces

To delete a space, you'll just call deleteSpace and include the ID; note this is irreversible, so triple check you have the right ID before moving forward. We have to include something in the return fields, so we'll select the underscore. As long as you get a 200 OK and a JSON response back, the deletion should be successful.

Request Response
Copy
1
2
3
4
5
mutation {
    	deleteFloor(input: { id: "SPCXWuZRuYs3YN12Syni3AbCd" }) {
    		_
    	}
    }