Buildings

All examples use these variables:

export BASE="https://api.mapped.com/v1/accounts/$ACCOUNT_ID/orgs/$ORG_ID"

The full parameters and responses of each route are in the API reference.

List buildings

GET /buildings returns a page of the org's buildings, ordered by id. Only buildings with a postal address are returned, because the others cannot be updated. The list can lag an update by up to a minute.

Query parameter	Type	Default	Meaning
`limit`	integer, 1 to 100	50	Buildings per page
`cursor`	string	none	Opaque; pass the `nextCursor` of the previous page

curl -s "$BASE/buildings?limit=2" -H "Authorization: Bearer $ACCESS_TOKEN"

grossArea is in square feet and is null when it is not set. When nextCursor is absent you have the last page. A bad limit (also a repeated limit) is 400 invalid_limit, and a bad cursor (also a repeated one) is 400 invalid_cursor. See List buildings.

Set a building's gross area

PUT /buildings/{buildingId}/gross-area sets one building's gross area, in square feet. It is asynchronous, like a batch: it is a batch of one. The call returns 202 Accepted at once and the update runs in the background; you poll its status. It is idempotent: setting the same value twice is harmless.

Body field	Type	Meaning
`grossArea`	number, `0` or more	Square feet. `0` is valid.
`createConnector`	boolean, default `false`	Allow creating the Admin Center connector if the org has none

buildingId matches ^[A-Za-z0-9_.-]{1,128}$.

Request
curl -s -X PUT "$BASE/buildings/bld_1/gross-area" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "grossArea": 52000 }'

Response (202 Accepted)
{
  "success": true,
  "data": {
    "batchId": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "statusUrl": "/v1/accounts/ACCOUNT_ID/orgs/ORG_ID/batches/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e"
  }
}

The Location header carries the same statusUrl. Poll it until the batch is completed; its single item is the result of the update:

curl -s "$BASE/batches/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Updates are recorded through an Admin Center connector in the org. If the org has none and createConnector is not true, the item is an error with connector_required; with true, the connector is created. The outcome of the update itself is never an HTTP status of the PUT: a building that is not in the org (building_not_found), one with no postal address (missing_postal_identity) and the other item errors are in the item's error, as for any batch (see Batches). See Set a building's gross area.

Starting an update counts toward the same limit as starting a batch (10 per minute per account; see Errors and limits). Without a background worker the call is 503 batches_unavailable.

These are refused before anything starts:

Status	`code`	Meaning
`400`	`invalid_gross_area`	`grossArea` is missing, not a number, or below 0
`400`	`invalid_create_connector`	`createConnector` is not a boolean
`400`	`invalid_building_id`	`buildingId` does not match the pattern
`400`	`bad_request`	The body is not a JSON object, is malformed, or is not `application/json`
`429`	`rate_limited`	Too many updates or batches started; see `Retry-After`
`502`	`jobs_unavailable`	The job could not be started and was cancelled
`503`	`batches_unavailable`	Batches and updates are not available right now

To update many buildings in one call, use a batch.

List buildings​

Set a building's gross area​

List buildings

Set a building's gross area