ArchDATUM Takeoff — Installation & Usage Guide

What this script does

The script connects to a live ArchiCAD session, reads your BIM model, extracts element quantities by CSI division, and builds a formatted Excel estimate workbook. It covers Divisions 02 through 26 — site through electrical. You get two output tabs: a summary by CSI division and a detailed line-item estimate with unit costs, quantities, and totals.

Quantities come from the model directly where ArchiCAD can supply them — wall areas, floor areas, door and window counts, roof area, MEP fixture counts. Line items the model cannot quantify get area-based defaults from your total heated floor area. Those cells are flagged yellow in the output so you know which numbers came from the model and which are estimates.

Prerequisites

1. Python 3.8 or later

Check your version first:

If Python is not installed:

• Mac: Install via Homebrew — brew install python — or download from python.org
• Windows: Download from python.org. During installation, check "Add Python to PATH" — without this the terminal will not find Python.

2. The archicad and openpyxl packages

The script installs these automatically on first run. To install manually:

3. ArchiCAD 29 running

The script connects to ArchiCAD via the JSON API (localhost, port 19723 by default). ArchiCAD must be open with a project loaded before you run the script.

Enabling the ArchiCAD JSON API

ArchiCAD 29 includes the JSON API as a built-in add-on. It should be active by default, but if the connection test above fails, check the following:

• 1 In ArchiCAD, go to Options → Add-On Manager
• 2 Find ArchiCAD JSON Interface in the list. Make sure it is checked / enabled.
• 3 The default port is 19723. If you changed it, update the port in the script's connection line near the top of the file: ACConnection.connect(port=19723)
• 4 Restart ArchiCAD after enabling the add-on, then re-run the connection test.

Model preparation

Do these four things before running to get clean output:

• ! Delete or hide reference panels and underlays. The script processes the full model scope. A reference plan from another project that is visible will be included in quantities. Turn it off or delete it before running.
• ! Name composites consistently. The composite name parser reads wall, slab, and roof composite names and auto-generates material line items. It recognizes terms like studs, GWB, brick, insulation, sheathing, metal studs. If your composites are named generically ("Wall Type 1"), the parser skips sub-items and reports the assembly total only.
• 3 Model spaces with the Zone tool. Heated floor area drives most MEP estimates. If zones are not modeled, the script falls back to total slab area — usable but less precise.
• 4 Place mechanical and plumbing objects from the library. Standard ArchiCAD library objects tagged as HVAC equipment and plumbing fixtures contribute to equipment and fixture counts. Custom objects without standard property assignments will not be counted.

Running the script

Step 1 — Download and save the script

Save ArchDATUM_Takeoff.py to a folder you can find easily. A dedicated scripts folder works well:

• Mac: ~/Documents/ArchiCAD Scripts/
• Windows: C:\Users\YourName\Documents\ArchiCAD Scripts\

Step 2 — Open Terminal (Mac) or Command Prompt (Windows)

Navigate to the folder containing the script:

Step 3 — Run with default output

Output saves to the same folder as the script with a timestamped filename: ArchDATUM_Takeoff_YYYYMMDD_HHMMSS.xlsx

Step 4 — Or specify an output folder

The script prints progress to the terminal as it runs. A typical model takes 15 to 60 seconds depending on complexity.

Reading the Excel output

Tab 1 — Summary

One row per CSI division. Shows total estimated cost and percentage of the overall hard cost budget. Use it to sanity-check division proportions against your own cost benchmarks or historical project data.

Tab 2 — Estimate (line-item detail)

Division 21 — Fire suppression lines

The script includes three fire suppression lines, all using the building's total heated floor area as the quantity. Delete the two lines that do not apply to your project type before presenting the estimate.

Unit costs are 2025–2026 benchmark national averages for a complete wet-pipe system including main, branch lines, heads, and inspector's test. Regional multipliers are not applied — adjust for your market.

Adjusting unit costs for your market

All unit costs are 2025–2026 benchmark national averages. Multiply by a city cost index for your market to regionalize. Common adjustments:

City cost index multipliers are approximate. Update the unit cost column in the Excel output directly — changes carry through to the totals automatically.

Troubleshooting

"Connection refused" or "Cannot connect to ArchiCAD"

ArchiCAD is not running, the JSON API add-on is not enabled, or the port does not match. Confirm ArchiCAD 29 is open and the API is active. See the Enabling the ArchiCAD JSON API section above.

Script runs but all quantities are zero

The model may not have elements matching the expected property names. This happens most often with projects started in ArchiCAD 24 or earlier. Check that your template uses standard ArchiCAD built-in property names.

Excel file opens but is blank

The script completed but found no elements. Check that the model is not in a hidden or filtered view state. Confirm you are connected to the correct project — the API connects to the frontmost open ArchiCAD window.

ModuleNotFoundError: No module named 'archicad'

If you are using a virtual environment, activate it first, then install.

Permission error writing the Excel file

The output folder is write-protected or does not exist. Use the --output flag to point to a folder you own.

Questions or issues

Email seaboldarch@gmail.com. Include the error message from the terminal and your ArchiCAD version.

Version history