Metadata-Version: 2.4
Name: dlubal.api.geo_zone_tool
Version: 0.2.1
Summary: Geo Zone Tool GraphQL client.
Author-email: Dlubal Software <api@dlubal.com>
License: MIT License
        
        Copyright (c) 2026 Dlubal Software
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://www.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
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: codespell>=2.3.0; extra == "dev"
Dynamic: license-file

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

## Import

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

## Authentication

A token is **optional**. These methods 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`.

```python
from dlubal.api import geo_zone_tool

# Anonymous client (public methods only)
geo_zone = geo_zone_tool.GeoZoneTool()

# Authenticated client (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.

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

```python
from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool()
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()
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 Seismic Hazard Data (ASCE)

Returns seismic hazard / design map parameters from USGS for a given US
location, risk category, site class, and ASCE version. `asce_version`
defaults to `AsceVersion.ASCE22`.

```python
from dlubal.api import geo_zone_tool

geo_zone = geo_zone_tool.GeoZoneTool()
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`.
- `GraphQLError` — the server returned a GraphQL `errors` array.
- `TransportError` — HTTP or WebSocket transport failure.

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

try:
    geo_zone_tool.GeoZoneTool().get_geo_locations(address="Berlin")
except GeoZoneError as exc:
    print(f"GeoZone call failed: {exc}")
```
