2021-05-12 API actions for Nested Locations

Nested locations provide a hierarchical tree structure to represent the structure or layout of a construction project.

This new feature will expand from our existing single location tier to up to five tiers of locations — not only can you now tie work and data objects (plans, photos, forms, etc) to specific locations, but you can also create more streamlined reports to communicate project status and progress.

You can read more about the announcement on our blog and review our help article for details.

Users can use the Fieldwire API to do key actions such as:

• Create, get, delete nested locations
• Edit the name of a location
• Batch create locations
• Get the full path of a location
• Get the # of tasks associated with a location and its children

Note: These new API changes will not impact any existing API calls.

The full API documentation can be found here.

For the remainder of this post, we will elaborate specifically on the new #batch_create endpoint for locations.

Batch creating Nested Locations

POST /api/v3/projects/:project_id/locations/batch_create

The body of the request should include an array of string arrays that represent full paths to be created.

Each index of a full path array represents the name of the location at that tier ["Tier 1 Name", "Tier 2 Name", ..., "Tier 5 Name"].

For example, a full path array of a Tier 3 location would be: ["Building 1", "Floor 1", "Room 1"]
which corresponds to the structure of Building 1 > Floor 1 > Room 1.

In this example, if Building 1 and Floor 1 do not already exist, they will be created during the batch_create request (in addition to Room 1).

Requests are idempotent -- if a request body comes in with [["Building 1", "Floor 1", "Room 1"], ["Building 1", "Floor 1", "Room 2"]], the final result will be:
Building 1 > Floor 1 > Room 1, Room 2

There is a uniqueness constraint for location names on the same tier for a given project: two locations under the same parent (including Tier 1 locations that have no parent) cannot have an identical name.

The response of the batch_create call is a list of locations that were successfully created from the request.

# POST /api/v3/projects/:project_id/sheets/batch_export

{
    "list_of_full_paths": [["Building 1", "Floor 1", "Room 1"], ["Building 1", "Floor 1", "Room 2"]]
}

# Response Body
# 201 Created
[
    {
        "id": "f556242e-f9e7-4e15-adbd-781c417eec59",
        "project_id": "2b46d493-cd32-47c2-8b60-1267b0dbc6fe",
        "location_id": null,
        "name": "Building 1",
        ...
    },
    {
        "id": "362c05a8-6046-4396-bc0f-478634b3eb36",
        "project_id": "2b46d493-cd32-47c2-8b60-1267b0dbc6fe",
        "location_id": "f556242e-f9e7-4e15-adbd-781c417eec59",
        "name": "Floor 1",
        ...
    },
    {
        "id": "c1fcf634-8686-4a89-888e-65dca76e28ff",
        "project_id": "2b46d493-cd32-47c2-8b60-1267b0dbc6fe",
        "location_id": "362c05a8-6046-4396-bc0f-478634b3eb36",
        "name": "Room 1",
        ...
    },
    {
        "id": "dabd3423-184e-4c03-8c6d-e2eac5b85cec",
        "project_id": "2b46d493-cd32-47c2-8b60-1267b0dbc6fe",
        "location_id": "362c05a8-6046-4396-bc0f-478634b3eb36",
        "name": "Room 2",
        ...
    }
]

🚧

Size Restriction

A maximum of 500 locations can be included in the total sum of full paths for a single batch create request.