Batches

A batch sets the gross area of 1 to 1,000 buildings of the org in the path. It returns immediately and runs in the background, as one job for the org that updates its buildings one after another. You then poll its status. The full parameters and responses are in the reference for starting a batch and for its status.

All examples use these variables:

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

A single update, PUT /buildings/{buildingId}/gross-area, is a batch of one: it answers the same 202 with a batchId and a statusUrl, and its status is read from the same route below. See Buildings.

Start a batch

POST /buildings/gross-area:batch

Body field	Type	Meaning
items	array of 1 to 1,000	The buildings to update
items[].buildingId	string, ^[A-Za-z0-9_.-]{1,128}$	A building of the org, once per batch; a mismatch is invalid_item
items[].grossArea	number, 0 or more	Square feet
createConnector	boolean, default false	As for one building

An item names only a building and its area. The org is the path's, so an item that names an orgId is refused.

curl -s -X POST "$BASE/buildings/gross-area:batch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "buildingId": "bld_1", "grossArea": 52000 },
      { "buildingId": "bld_2", "grossArea": 18500 }
    ]
  }'

The answer is 202 Accepted, and the Location header carries the same statusUrl. A body that is invalid is refused with 400 before anything starts: invalid_items (not 1 to 1,000 items), invalid_item (an item is malformed, or names an orgId), duplicate_item (a buildingId repeats), invalid_create_connector or bad_request (not a JSON object, malformed, or not application/json).

Poll its status

GET /batches/{batchId}

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

• status is queued, running or completed. completedAt is present when it is completed. A batch is completed when its job has ended, whether or not every item succeeded: read counts and the items.
• Each item is pending, ok or error. An error item carries a code: building_not_found, connector_required, missing_postal_identity, invalid_gross_area, invalid_building_id, upstream_error (the update failed on our side) or job_failed (the job did not complete).
• Poll every few seconds. Progress is coarse for short batches: a batch of a few seconds can go from queued straight to completed.

Things to know

• Results are kept for 3 days. After that, the items of a finished batch are left out and counted in counts.unreported.
• job_failed means unknown, not "not applied". The job did not complete, so some of its other items may already have been applied. Check the buildings before retrying.
• A batch that cannot start is cancelled. If starting it fails, the answer is 502 jobs_unavailable; some updates may already have been applied.
• A batch is private to its org. A batch of another org or account is indistinguishable from a missing one: both are 404 not_found. So is a batch id this API never issued.
• Starting batches is rate limited more strictly than reading. At most 10 batch start requests (a single update counts as one) are allowed per minute per account. See Errors and limits.
• Batches may be unavailable (503 batches_unavailable) when the service has no background worker configured. A status that cannot be read for the moment is 503 jobs_unavailable or 503 results_unavailable: retry.