User Guide

This guide is for developers who consume dlubal.api.geo_zone_tool in their applications.

Install

pip install dlubal.api.geo_zone_tool

Import

from dlubal.api import geo_zone_tool

Authentication

A token is optional. These methods are public and work without one:

• get_geo_locations
• get_load_zone_standards
• get_hazard_data

The remaining methods require a token; calling them without one raises a ValueError.

from dlubal.api import geo_zone_tool

# Public methods only
geo_zone = geo_zone_tool.GeoZoneTool()

# All methods
geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")

Sync vs Async

GeoZoneTool is synchronous. AsyncGeoZoneTool exposes the same methods as coroutines for use inside an event loop.

import asyncio
from dlubal.api import geo_zone_tool

async def main():
    geo_zone = geo_zone_tool.AsyncGeoZoneTool("<your-token>")
    user = await geo_zone.get_user_data()
    print(user)

asyncio.run(main())

The examples below use the sync client.

Common Enums

• geo_zone_tool.Language (EN, DE, IT, CS, FR, ES, PT, PL, RU, ZH)
• geo_zone_tool.LoadZoneType (SNOW, WIND, SEISMIC, TORNADO)
• geo_zone_tool.ScreenshotType (PNG, JPEG)
• geo_zone_tool.RiskCategory (I, II, III, IV)
• geo_zone_tool.SiteClass (DEFAULT, A, B, BC, C, CD, D, DE, E)
• geo_zone_tool.AsceVersion (ASCE22, ASCE16)

Examples

Find Locations

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool()  # public method
locations = geo_zone.get_geo_locations(
    address="Flugplatzweg 6, 14913, Germany",
    language=geo_zone_tool.Language.EN,
)

for loc in locations.locations:
    print(loc)

Get User Info

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
user = geo_zone.get_user_data()
print(user)

Get Available Standards

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool()  # public method
standards = geo_zone.get_load_zone_standards(
    country_code="DE",
    language=geo_zone_tool.Language.EN,
)

print(f"{standards.country} ({standards.country_code})")
for group in standards.type_groups:
    print(f"  {group.name}")
    for item in group.load_zones:
        print(f"    {item.standard.name} / {item.annex.name}")

Get Load Zone Characteristics

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
result = geo_zone.get_load_zone_characteristics(
    address="Flugplatzweg 6, 14913, Germany",
    load_zone_type=geo_zone_tool.LoadZoneType.SNOW,
    standard="EN 1991-1-3",
    annex="DIN EN 1991-1-3",
    layer_id=1,
    language=geo_zone_tool.Language.EN,
)

print(result)

Get Screenshot (Base64)

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
screenshot = geo_zone.get_load_zone_screenshot(
    address="Flugplatzweg 6, 14913, Germany",
    load_zone_type=geo_zone_tool.LoadZoneType.SNOW,
    standard="EN 1991-1-3",
    annex="DIN EN 1991-1-3",
    layer_id=1,
    zoom=6,
    screenshot_type=geo_zone_tool.ScreenshotType.JPEG,
    screenshot_quality=80,
)

print(screenshot.screenshot[:40])  # base64 prefix

Stream PDF Progress

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
for msg in geo_zone.get_load_zone_pdf(
    address="Flugplatzweg 6, 14913, Germany",
    standard="EN 1991-1-3",
    annex="DIN EN 1991-1-3",
    layer_id=1,
):
    print(f"[{msg.current_step}/{msg.steps}] {msg.message}")

Get Final PDF (Base64)

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
pdf_result = geo_zone.get_load_zone_pdf_result(
    address="Flugplatzweg 6, 14913, Germany",
    standard="EN 1991-1-3",
    annex="DIN EN 1991-1-3",
    layer_id=1,
)

if pdf_result is not None:
    print(pdf_result.name)
    print(pdf_result.pdf[:40])  # base64 prefix

Get Seismic Hazard Data (ASCE)

Returns seismic hazard / design map parameters from USGS for a given US location, risk category, and site class. Only AsceVersion.ASCE22 (the default) is currently available; ASCE16 raises TransportError.

from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool()  # public method
result = geo_zone.get_hazard_data(
    latitude="37.7749",
    longitude="-122.4194",
    risk_category=geo_zone_tool.RiskCategory.II,
    site_class=geo_zone_tool.SiteClass.D,
    asce_version=geo_zone_tool.AsceVersion.ASCE22,
)

if result.data is not None:
    data = result.data
    print(f"reference: {result.reference_document}")
    print(f"Sds = {data.sds}")
    print(f"Sd1 = {data.sd1}")
    print(f"SDC = {data.sdc}")

Error Handling

All SDK errors derive from geo_zone_tool.GeoZoneError:

• ValidationError — invalid input (empty strings, out-of-range numbers). It subclasses ValueError, so except ValueError still catches it. A wrong enum type raises TypeError.
• TransportError — a network/transport failure or a non-OK server response.

from dlubal.api import geo_zone_tool
from dlubal.api.geo_zone_tool import GeoZoneError

try:
    geo_zone_tool.GeoZoneTool("<your-token>").get_geo_locations(address="Berlin")
except GeoZoneError as exc:
    print(f"GeoZone call failed: {exc}")