GeoZone Public API

一个 GraphQL API，可为全球任意坐标返回结构荷载区数据、地理特征和 PDF 报告。

7 个查询1 个订阅Bearer 认证

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

Web 应用

GeoZone 工具也可作为交互式 Web 应用程序访问 dlubal.com. 在地图上选择任意位置，即可立即查看所有结构荷载区值。

GeoZone Web 应用

身份验证

大多数查询需要在 Authorization 标头中传递 Bearer 令牌：

Authorization:Bearer YOUR_TOKEN

标记为公开的查询不需要身份验证。其他所有查询每次请求消耗一个 API 额度。

getLoadZoneCharacteristics

查询需要认证

返回给定坐标的荷载区分类和所有特征。接受 loadZoneId（来自 findLoadzones）、layerId 以及十进制字符串格式的纬度/经度。响应包含地址详情、匹配区域和有序的结构特征列表。

字段 code 可以是 OK、COUNTRY_CHANGED（服务器自动选择了更合适的标准）、ANNEX_CHANGED 或 ERROR。

雪荷载区

风荷载区

地震区

graphql

query {
  getLoadZoneCharacteristics(
    input: {
      address: "Munich, Germany"
      type: SNOW
      standard: "EN 1991-1-3"
      annex: "Germany"
      layerId: 1
    }
    language: EN
  ) {
    code
    message
    geoLocation {
      latitude longitude altitude
      street zip city state country countryCode
    }
    characteristics {
      standard
      annex
      zoneCharacteristics {
        id
        zone { value }
        characteristics {
          name calculatedValue
          nameHtml unitsHtml description
          decimalPlaces sequence
        }
      }
    }
    noLiability
  }
}

getLoadZoneCharacteristicsV1

查询需要认证

getZoneCharacteristics 的旧版本。返回不含地址数据或完整特征序列的精简响应。为向后兼容而保留——新集成应使用 getZoneCharacteristics。

graphql

query {
  getLoadZoneCharacteristicsV1(
    input: {
      address: "Munich, Germany"
      type: SNOW
      standard: "EN 1991-1-3"
      annex: "Germany"
      layerId: 1
    }
    language: EN
  )
}

getGeoLocations

查询公开

地理编码查询——将自由格式地址转换为坐标结果。无需身份验证。返回最多 10 个排名结果，包含街道、城市、州/省、国家、邮政编码和十进制坐标。

地址搜索

graphql

query {
  getGeoLocations(
    address: "Altdorf, Uri, Switzerland"
    language: EN
  ) {
    latitude longitude altitude
    displayName street zip city state country countryCode
  }
}

getLoadZoneScreenshot

查询需要认证

生成以给定坐标为中心的地图截图，以 base64 编码的 PNG 或 JPEG 格式输出。适用于在报告或仪表板中嵌入区域地图。

graphql

query {
  getLoadZoneScreenshot(
    input: {
      address: "Munich, Germany"
      type: SNOW
      standard: "EN 1991-1-3"
      annex: "Germany"
      layerId: 1
      zoom: 8
      screenshotType: { type: PNG quality: 90 }
    }
    language: EN
  )
}

getLoadZoneStandards

查询公开

返回荷载区类型、标准、国家附录和图层的完整层级结构。用于填充选择器或发现有效的 loadZoneId 值及其图层 ID、区域标签和颜色。

graphql

query {
  getLoadZoneStandards(
    countryCode: "DE"
    language: EN
  ) {
    name
    standards {
      name
      annexes {
        name
        actual
        layers { id name }
      }
    }
  }
}

findLoadzones

查询需要认证

返回按类型分组的荷载区紧凑列表——适合发现有效的 loadZoneId / layerId 对。

graphql

query {
  findLoadzones(
    countryCode: "DE"
    language: EN
  ) {
    country
    countryCode
    typeGroups {
      name
      loadzones {
        standard annex loadzoneId
        layers { id name }
      }
    }
  }
}

响应示例

json

{
  "data": {
    "findLoadzones": {
      "country": "Germany",
      "countryCode": "DE",
      "typeGroups": [
        {
          "name": "Snow",
          "loadzones": [
            {
              "standard": "EN 1991-1-3",
              "annex": "Germany",
              "loadzoneId": "snow-eu-en-1991",
              "layers": [{ "id": 1, "name": null }]
            }
          ]
        },
        {
          "name": "Wind",
          "loadzones": [
            {
              "standard": "EN 1991-1-4",
              "annex": "Germany",
              "loadzoneId": "wind-eu-en-2005",
              "layers": [{ "id": 1, "name": null }]
            }
          ]
        }
      ]
    }
  }
}

getUserData

查询需要认证

返回已认证用户的电子邮件地址、信用余额以及当前计费周期内剩余的 API 点击次数。

graphql

query {
  getUserData {
    email
    clicks
  }
}

getPdf

订阅需要认证

通过 WebSocket 连接（graphql-ws GraphQL 订阅）生成完整的荷载区 PDF 报告。服务器流式传输进度更新；最终消息包含 base64 编码的 PDF 和建议的文件名。

WebSocket 端点： wss://team-w.dlubal.com/api/geo-zone/pub/graphql

graphql

subscription {
  getPdf(
    pdfInput: {
      address: "Munich, Germany"
      standard: "EN 1991-1-3"
      annex: "Germany"
      layerId: 1
    }
    language: EN
  ) {
    currentStep
    steps
    message
    pdfResult { pdf name }
  }
}

JavaScript 客户端示例

javascript

import { createClient } from "graphql-ws";

const client = createClient({
  url: "wss://team-w.dlubal.com/api/geo-zone/pub/graphql",
  connectionParams: { Authorization: "Bearer YOUR_TOKEN" },
});

const unsubscribe = client.subscribe(
  {
    query: `subscription {
      getPdf(pdfInput: {
        address: "Munich, Germany"
        standard: "EN 1991-1-3"
        annex: "Germany"
        layerId: 1
      } language: EN) {
        currentStep steps message
        pdfResult { pdf name }
      }
    }`,
  },
  {
    next({ data }) {
      const step = data?.getPdf;
      console.log(`${step.currentStep}/${step.steps} — ${step.message}`);
      if (step.pdfResult) {
        // step.pdfResult.pdf is base64-encoded
        unsubscribe();
      }
    },
    error(err) { console.error(err); },
    complete()  { console.log("Done"); },
  }
);

枚举

LanguageEnum

值	语言
EN	English
DE	German
FR	French
IT	Italian
ES	Spanish
PT	Portuguese
PL	Polish
CS	Czech
RU	Russian
ZH	Chinese

LoadzoneTypeEnum

值	描述
SNOW	Snow load zones (EN 1991-1-3)
WIND	Wind load zones (EN 1991-1-4)
EARTHQUAKE	Seismic zones (EN 1998)
TORNADO	Tornado zones (US only)

ScreenshotTypeEnum

值	描述
PNG	Lossless PNG image
JPEG	Compressed JPEG image

输入类型

CharacteristicsInput

字段	类型	描述
address	String!	Free-text address or place name
type	LoadzoneTypeEnum	Zone type filter (SNOW, WIND, EARTHQUAKE, TORNADO)
standard	String	Standard name filter
annex	String	Annex / national annex filter
layerId	Int	Layer ID within the standard

GetLoadzoneScreenshotPublicInput

字段	类型	描述
address	String!	Free-text address or place name
type	LoadzoneTypeEnum	Zone type filter
standard	String	Standard name filter
annex	String	Annex filter
layerId	Int	Layer ID
zoom	Int	Map zoom level (default 5)
map	String	Map tile style
layerOrder	Int	Layer rendering order
screenshotType	ScreenshotTypeInput	Image format and quality

ScreenshotTypeInput

字段	类型	描述
type	ScreenshotTypeEnum!	PNG or JPEG (default PNG)
quality	Int!	JPEG quality 0–100 (default 90)

GetLoadzonePdfInput

字段	类型	描述
address	String!	Free-text address or place name
standard	String	Standard name filter
annex	String	Annex filter
layerId	Int	Layer ID

输出类型

CharacteristicsResponseMiaType

字段	类型	描述
code	String!	Response status code
message	String	Human-readable message when code ≠ OK
geoLocation	GeofinderDataType	Resolved location data
characteristics	[CharacteristicsLoadzoneType2]	Per-standard zone results
noLiability	String	Disclaimer text

CharacteristicsLoadzoneType2

字段	类型	描述
standard	String!	Standard name
annex	String!	Annex name
zoneCharacteristics	CharacteristicsLayerType2!	Layer result

CharacteristicsLayerType2

字段	类型	描述
id	Int!	Layer ID
zone	CharacteristicsZoneType2!	Matched zone value
characteristics	[CharacteristicsVariableType]!	Ordered load values

CharacteristicsVariableType

字段	类型	描述
name	String!	Parameter name (plain text)
nameHtml	String!	Parameter name (HTML)
calculatedValue	String	Computed value
unitsHtml	String!	Units (HTML)
description	String!	Parameter description
decimalPlaces	Int!	Display precision
sequence	Int!	Display order

GeofinderDataType

字段	类型	描述
latitude	String!	Resolved latitude
longitude	String!	Resolved longitude
altitude	String!	Elevation
street	String	Street name and number
zip	String	Postal code
city	String	City / municipality
state	String	State or region
country	String	Country name
countryCode	String	ISO country code

GeoLocationType

字段	类型	描述
latitude	String!	Latitude
longitude	String!	Longitude
altitude	String!	Elevation
displayName	String	Full formatted address
street	String	Street name and number
zip	String	Postal code
city	String	City / municipality
state	String	State or region
country	String	Country name
countryCode	String	ISO country code

UserDataType

字段	类型	描述
email	String!	Account email address
clicks	Int!	Remaining API calls this billing period

LoadzoneGroupShortType

字段	类型	描述
country	String!	Country name
countryCode	String!	ISO country code
typeGroups	[LoadzoneTypeGroupType]!	Zones grouped by type

LoadzoneShortType

字段	类型	描述
standard	String!	Standard name
annex	String!	Annex name
loadzoneId	String!	Unique load zone identifier
layers	[LoadzoneLayerShortType]!	Available layers

PdfProgressType

字段	类型	描述
currentStep	Int!	Steps completed
steps	Int!	Total steps
message	String!	Status message
pdfResult	PdfResultType	Present on final message only

PdfResultType

字段	类型	描述
pdf	String!	Base64-encoded PDF
name	String!	Suggested filename