Extracting Room Data from Revit using SpecklePy

pip install specklepy pandas

import os

from dotenv import load_dotenv
from specklepy.api.client import SpeckleClient
from specklepy.api import operations
from specklepy.objects import Base
from specklepy.transports.server import ServerTransport
import pandas as pd

load_dotenv()

SPECKLE_TOKEN = os.getenv("SPECKLE_TOKEN")# you can generate a new token from the DEVELOPER SETTINGS
SPECKLE_SERVER_URL = os.getenv("SPECKLE_SERVER_URL", "https://app.speckle.systems")

if not SPECKLE_TOKEN:
    raise EnvironmentError("SPECKLE_TOKEN is not set. Add it to your .env file.")

client = SpeckleClient(host=SPECKLE_SERVER_URL)# here add your custom server URL 
client.authenticate_with_token(SPECKLE_TOKEN)

project_id = "your_project_id" # here add your project ID, you can find it in the URL of your project, after "projects/", for example in "https://app.speckle.systems/projects/e23d2d5041/models/ab02b98507" the project ID is "e23d2d5041"
version_id = "your_version_id" # here add your version ID, you can find it under Share > Copy ID in the web 3D viewer

# Get version metadata to find the referenced object ID
version = client.version.get(version_id, project_id)
referenced_object_id = version.referenced_object

# next create a server transport - this is the vehicle through which you will send and receive
transport = ServerTransport(stream_id=project_id, client=client)

# Download the full object graph. Note that this is an expensive operation, as it retrieves all objects in the model, so it may take some time for large models.
received_base = operations.receive(referenced_object_id, transport)

# Flatten root object and get all objects in a list
def flatten_base(base: Base) -> Iterable[Base]:
    """Flatten a base object into an iterable of bases.
    
    This function recursively traverses the `elements` or `@elements` attribute of the 
    base object, yielding each nested base object.

    Args:
        base (Base): The base object to flatten.

    Yields:
        Base: Each nested base object in the hierarchy.
    """
    # Attempt to get the elements attribute, fallback to @elements if necessary
    elements = getattr(base, "elements", getattr(base, "@elements", None))

    if elements is not None:
        for element in elements:
            yield from flatten_base(element)
    
    yield base

all_objects = list(flatten_base(received_base))

# Helper function to filter objects by category
def filter_objects_by_category(all_objects, filter_categories):
    """
    Filters objects by category and returns a list of matching objects and their IDs.

    Parameters:
    all_objects (list): List of objects to filter.
    filter_categories (list): List of categories to filter by.

    Returns:
    list: filtered_objects
    """
    filtered_objects = []

    items = []

    for i in all_objects:
        if hasattr(i, "category"):  # Check if the object has the "category" attribute
            if i.category in filter_categories:  # Check if the category matches the filter list
                filtered_objects.append(i)  # Append the whole object to the items list
        else:
            continue  # Skip if "category" does not exist

    return filtered_objects

# Helper function to get nested value from a dict using a path of keys
def get_nested_value(data, path, extract_value=True):
    """
    Navigate a nested dict using a list of keys.
    If the final node is a Revit parameter dict (has a 'value' key), returns its value.

    Parameters:
    data (dict): The dict to traverse (typically obj.properties).
    path (list[str]): Ordered list of keys, e.g.
                      ['Parameters', 'Instance Parameters', 'Identity Data', 'Number']
    extract_value (bool): If True and the leaf node contains a 'value' key, return that.

    Returns:
    The resolved value, or None if any key in the path is missing.
    """
    current = data
    for key in path:
        if not isinstance(current, dict):
            return None
        current = current.get(key)
        if current is None:
            return None # If any key is missing, return NaN in the DataFrame
    if extract_value and isinstance(current, dict) and 'value' in current:
        return current['value']
    return current

# Helper function to extract specified fields from a list of objects using flexible nested paths
def extract_object_data(objects, field_paths, include_defaults=True):
    """
    Extract data from a list of DataObjects using flexible nested field paths.

    Returns:
    list[dict]: One dict per object with the resolved values.
    """
    results = []
    for obj in objects:
        properties = getattr(obj, 'properties', {}) or {}
        row = {}

        if include_defaults:
            row['id'] = getattr(obj, 'id', None) # Include the object ID by default, or other parameters like 'type' if needed.

        for col_name, path in field_paths.items():
            row[col_name] = get_nested_value(properties, path)

        results.append(row)
    return results

# Define the field paths for the desired parameters, use the Speckle 3D Viewer to inspect the structure of the properties and adjust paths as needed. 
# Select one of the rooms in the viewer, inspect its properties and find the path to the parameters you want to extract. 
# The path is a list of keys to navigate through the nested dictionaries in obj.properties. For example, if the parameter is located at obj.properties['Parameters']['Instance Parameters']['Identity Data']['Number'], 
# then the path would be ['Parameters', 'Instance Parameters', 'Identity Data', 'Number'].
field_paths = {
    'Number':       ['Parameters', 'Instance Parameters', 'Identity Data', 'Number'],
    'Name':         ['Parameters', 'Instance Parameters', 'Identity Data', 'Name'],
    'Occupant':     ['Parameters', 'Instance Parameters', 'Identity Data', 'Occupant'],
    'Floor Finish': ['Parameters', 'Instance Parameters', 'Identity Data', 'Floor Finish'],
    'Level':        ['Parameters', 'Instance Parameters', 'Constraints', 'Level'],
    'Area':         ['Parameters', 'Instance Parameters', 'Dimensions', 'Area'],
    'Volume':       ['Parameters', 'Instance Parameters', 'Dimensions', 'Volume'],
    'Perimeter':    ['Parameters', 'Instance Parameters', 'Dimensions', 'Perimeter'],
    'Unbounded Height':    ['Parameters', 'Instance Parameters', 'Dimensions', 'Unbounded Height'],
}

room_data = filter_objects_by_category(all_objects, ['Rooms']) # Make sure to extract only rooms
data = extract_object_data(room_data, field_paths) # Extract the data using the defined field paths
df_rooms = pd.DataFrame(data)
df_rooms.head()