Metadata-Version: 2.4
Name: dlubal.api.geo_zone_tool
Version: 0.1.3
Summary: Geo Zone Tool GraphQL client.
Author-email: Dlubal Software <api@dlubal.com>
Keywords: GeoZone,Structural Analysis,Dlubal
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.3
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"

# User Guide

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

## Install

```bash
pip install dlubal.api.geo_zone_tool
```

## Authentication

Every API call requires a valid GeoZone token.

```python
TOKEN = "<your-token>"
```

## Import

```python
from dlubal.api import geo_zone_tool
```

## Usage

All services require a token, so create one `GeoZoneTool` instance and call
services through it.

```python
from dlubal.api import geo_zone_tool

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

## 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`) — ASCE 7-22
- `geo_zone_tool.SiteClass` (`DEFAULT`, `A`, `B`, `BC`, `C`, `CD`, `D`, `DE`, `E`) — ASCE 7-22

## Examples

### Find Locations

```python
from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
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

```python
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

```python
from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
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

```python
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)

```python
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

```python
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)

```python
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 ASCE 7-22 Seismic Parameters

Returns seismic design map parameters from USGS for a given US location,
risk category, and site class.

```python
from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool("<your-token>")
result = geo_zone.get_asce722(
    latitude="37.7749",
    longitude="-122.4194",
    risk_category=geo_zone_tool.RiskCategory.II,
    site_class=geo_zone_tool.SiteClass.D,
)

if result.code == "OK" and result.data is not None:
    data = result.data
    print(f"Sds = {data.sds}")
    print(f"Sd1 = {data.sd1}")
    print(f"SDC = {data.sdc}")
```

## Error Behavior

- `ValueError`: empty strings, negative numeric values.
- `TypeError`: wrong enum type used in function call.
- `RuntimeError`: GraphQL response errors or WebSocket subscription errors.
- `requests.HTTPError`: HTTP transport failures.

## API Endpoint

The package targets:

- `https://team-w.dlubal.com/api/geo-zone/pub/graphql`
