Setting user parameters

There are a few procedures in POLARIS that require user-provided parameters, such as API keys. To handle these parameters in a user-friendly way, POLARIS uses a configuration file that is stored in the user’s configuration directory.

Once set, these values will remain available until the user changes them or deletes the configuration file.

sphinx_gallery_thumbnail_path = ‘../../examples/working_with_models/parameters.png’

from polaris.utils.user_configs import UserConfig
import json

# Most configuration values are initialized empty
# -----------------------------------------------

for k, v in json.loads(UserConfig().model_dump_json()).items():
    print(f"{k}: {v}")

census_api:
mobility_database_api:
nrel_api:
last_model_opened: /tmp
osm_url: http://overpass-api.de/api
overture_url: s3://overturemaps-us-west-2/release/2025-09-24.0

2. Setting values

You can set your own API values (example below uses dummy values). Setting them automatically saves to the user configuration file.

UserConfig().census_api = "sk-4f8b2c1e7d9a4e3b8f6c2d1a0b5e7c9f"
UserConfig().mobility_database_api = "mdb-4f8b2c1e7d9a4e3b8f6c2d1a0b5e7c9f-1234567890abcdef1234567890abcdef12345678sadf"

Loading them now will return the values you set

---

for k, v in json.loads(UserConfig().model_dump_json()).items():
    print(f"{k}: {v}")

census_api: sk-4f8b2c1e7d9a4e3b8f6c2d1a0b5e7c9f
mobility_database_api: mdb-4f8b2c1e7d9a4e3b8f6c2d1a0b5e7c9f-1234567890abcdef1234567890abcdef12345678sadf
nrel_api:
last_model_opened: /tmp
osm_url: http://overpass-api.de/api
overture_url: s3://overturemaps-us-west-2/release/2025-09-24.0