Back to Lessons

M4-01

Revit API Parameters Overview

Parameters are very important in Revit so understanding how to work with them in Revit API is crucial! Let me show you an overview of parameters in Revit API in this lesson.

Back to Lessons

M4-01

Revit API Parameters Overview

Parameters are very important in Revit so understanding how to work with them in Revit API is crucial! Let me show you an overview of parameters in Revit API in this lesson.

Resources

Docs: Parameter

Docs: StorageType Enumeration

Downloads

Revit 2023 File with Parameters

Summary

Parameters in Revit API

Let's have an overview of Parameters in Revit API.

There are 5 different types of parameters:

Built-In Parameters
Shared Parameters
Project Parameters
Global Parameters
Family Parameters

Let's focus on the first 3 types of the parameters and they also share the same Parameter Class in Revit API.

Parameters Overview in Revit API

Let's have an overview of Parameters in Revit API.

We can explore them inside of Revit Lookup to see actual values returned by different properties.

👉 Select an Element(Wall) -> Revit Lookup -> Snoop Selected -> Parameters

You will see a menu with a list of parameters on the left and properties and methods of selected parameter on the right.

By exploring this menu we can learn everything we need to know about our parameters and understand how to get them in the code.

Definition

Let's start looking at the properties. You will notice that the first property is Definition, and it has a few useful properties we want to know about.

Definition

Let's start looking at the properties. You will notice that the first property is Definition, and it has a few useful properties we want to know about.

Definition

Let's start looking at the properties. You will notice that the first property is Definition, and it has a few useful properties we want to know about.

This property will return you InternalDefinition of the Parameter. This class has the following useful properties:

Name
ParameterGroup
BuiltInParameter
VariesAcrossGroups

Parameter properties

Let's get back to Parameter class and have a look at its properties.

We can get properties like:

IsReadOnly
HasValue
IsShared
StorageType

These properties are very straight-forward, but let's talk about StorageType.

Parameter properties

Let's get back to Parameter class and have a look at its properties.

We can get properties like:

IsReadOnly
HasValue
IsShared
StorageType

These properties are very straight-forward, but let's talk about StorageType.

Parameter properties

Let's get back to Parameter class and have a look at its properties.

We can get properties like:

IsReadOnly
HasValue
IsShared
StorageType

These properties are very straight-forward, but let's talk about StorageType.

StorageType

StorageType is an Enumeration, so we can have a look inside of Revit API Docs, and see all possible values. Here are all possible StorageType values👇.

But wait, I thought Revit has far more Data Types? Not Exactly.

It's True that Revit has many Types for our Parameters.
But it only uses 4 in Revit API for all these parameters.

All these parameter types use one of the following StorageType in Revit API:

Double
ElementId
Integer
String

Even types like Yes/No parameter.

Obviously it's a Boolean parameter, but Revit API uses Integer to define values (0 = No, 1 = Yes).

Parameter methods

Also we can look at the methods. Methods are mainly used to get a value of the parameter.

There are the following methods available:

💡 If you look in Revit Lookup it will become very obvious which one to use, because you will see the actual values that would be returned.

But also you can look at StorageType property and then you will know if parameter uses Double, ElementId, Integer or String StorageType.

💡Keep in mind that Revit API uses feet as internal units, so whenever your parameters have a unit associated with them, values are going to be stored in feet. That's why when we explore Revit Lookup we can see different values in AsDouble and AsValueString.

💡AsValueString is not getting the real value, but sort of a formatted value.

So in case of Area parameters, you will see a value in feet in AsDouble, but AsValueString will return you a rounded value in your project's units.

In case of Material, AsElementId will return you an actual MaterialId, while AsValueString will return you only the name of that material.

Parameter methods

Also we can look at the methods. Methods are mainly used to get a value of the parameter.

There are the following methods available:

💡 If you look in Revit Lookup it will become very obvious which one to use, because you will see the actual values that would be returned.

But also you can look at StorageType property and then you will know if parameter uses Double, ElementId, Integer or String StorageType.

💡AsValueString is not getting the real value, but sort of a formatted value.

So in case of Area parameters, you will see a value in feet in AsDouble, but AsValueString will return you a rounded value in your project's units.

In case of Material, AsElementId will return you an actual MaterialId, while AsValueString will return you only the name of that material.

Parameter methods

Also we can look at the methods. Methods are mainly used to get a value of the parameter.

There are the following methods available:

💡 If you look in Revit Lookup it will become very obvious which one to use, because you will see the actual values that would be returned.

But also you can look at StorageType property and then you will know if parameter uses Double, ElementId, Integer or String StorageType.

💡AsValueString is not getting the real value, but sort of a formatted value.

So in case of Area parameters, you will see a value in feet in AsDouble, but AsValueString will return you a rounded value in your project's units.

In case of Material, AsElementId will return you an actual MaterialId, while AsValueString will return you only the name of that material.

Type Parameters

❌ Also some of you will try to get Type parameters from instance elements, and that won't work!

Element and ElementType are 2 different objects in Revit API ! Surely, they are related to one another, but you need to be aware what you are working with.

So if you want to get a type parameter, you would need to get Type object first, and then use the same methods to get a type parameter.

👇 Here is an example of getting Instance and Type Parameters

#👉 Get an Element!
elem = ... # 

#1️⃣ Get Instance Parameters
instance_params = elem.Parameters

#2️⃣ Get Type Parameters
el_type_id    = elem.GetTypeId()
el_type       = doc.GetElement(el_type_id)
type_params   = el_type.Parameters

Read parameters with python

Let's apply all this theory.

I am going to write a code snippet that will iterate through all the instance parameters and we will get different properties and methods.

💡 You wouldn't do that in your scripts, but I think it's good to do it once to understand what and how we can get out of the parameters.

#⬇️ IMPORTS
from Autodesk.Revit.DB import *
from Autodesk.Revit.UI.Selection import ObjectType, Selection

#📦 VARIABLES
uidoc = __revit__.ActiveUIDocument
doc   = __revit__.ActiveUIDocument.Document

selection = uidoc.Selection # type: Selection

#🧬 FUNCTIONS
def get_param_value(param):
    """Get a value from a Parameter based on its StorageType."""
    value = None
    if param.StorageType == StorageType.Double:
        value = param.AsDouble()
    elif param.StorageType == StorageType.ElementId:
        value = param.AsElementId()
    elif param.StorageType == StorageType.Integer:
        value = param.AsInteger()
    elif param.StorageType == StorageType.String:
        value = param.AsString()
    return value


#🔷 Pick Object
ref_picked_object = selection.PickObject(ObjectType.Element)
picked_object     = doc.GetElement(ref_picked_object)

for p in picked_object.Parameters:
    print("Name: {}".format(p.Definition.Name))
    print("ParameterGroup: {}".format(p.Definition.ParameterGroup))
    print("BuiltInParameter: {}".format(p.Definition.BuiltInParameter))
    print("IsReadOnly: {}".format(p.IsReadOnly))
    print("HasValue: {}".format(p.HasValue))
    print("IsShared: {}".format(p.IsShared))
    print("StorageType: {}".format(p.StorageType))
    print("Value: {}".format(get_param_value(p)))
    print("AsValueString(): {}".format(p.AsValueString()))
    print('-'*100)

This Snippet will let you pick an element and then iterate through all available parameters and print properties that we selected.

Also notice that I created a function get_param_value(p) to get parameter values based on their StorageType and AsValueString(), so you will be able to compare values that you get.

👀 Here is the result that this snippet will show in the console.

HomeWork

❗Try to use the code snippet to read parameter properties of different Category.

💼 Also try to modify this snippet to read all Type parameters.

👆 You have a snippet written in the post above on how to get type parameters!

#👉 Get an Element!
elem = ... # 

#1️⃣ Get Instance Parameters
instance_params = elem.Parameters

#2️⃣ Get Type Parameters
el_type_id    = elem.GetTypeId()
el_type       = doc.GetElement(el_type_id)
type_params   = el_type.Parameters

⌨️ Happy Coding!

Complete Lesson

Questions:

Why Revit parameters have so many types when we only need 4 in Revit API?

Discuss the lesson:

P.S. Sometimes this chat might experience connection issues.
Please be patient or join via Discord app so you can get the most out of this community and get access to even more chats.