1. Home
  2. RZRisk
  3. RZRisk 2.0
  4. API Documentation

API Documentation

Version 3 – April 10, 2013

Overview

RedZone’s RZRisk API is a standard SOAP web service (Simple Object Access Protocol) which exposes a single “getHazard” method. The service is called with an HTTP POST in which the message body is an XML document (the “Request). The Request is a serialized object having specific properties and datatypes expressed as XML elements. Similarly, the service responds with an XML document (the “Response”) which is also a serialized object having specific properties and datatypes corresponding to its XML elements.

Most modern programming languages have facilities which will auto-generate the appropriate object structures from the published WSDL (Web Service Description Language). The WSDL references a separate XSD document (XML Schema Definition) which precisely describes the properties and datatypes involved.

The RZRisk Web Service WSDL is available from: https://…/rzriskws/rzrisk.wsdl

The RZRisk Web Service XSD is available from: https://…/rzriskws/rzrisk-schema.xsd

This technical documentation describes the Request and Response structures in more detail by defining the content of each element and clarifying which are expected in the Request and which are returned in the Response. Additional comments are included where appropriate.

Request/Response

  1. REQUEST
    1. The HazardRequest message body must include the following elements as arguments:
      1. username – REQUIRED: the user name assigned to your account
      2. password – REQUIRED: the password assigned to your account
      3. location – REQUIRED: either a “Point” (1.2) or “BasicAddress” (1.3) Type as described below
      4. Only one location type is expected. If it does not exist, or more than one exists, the service will return an INVALID_LOCATION error.
    2. A “Point” Type consists of the following elements:
      1. latitude – REQUIRED: the latitude in decimal degrees (north is positive, south is negative)
      2. longitude – REQUIRED: the longitude in decimal degrees (east is positive, west is negative)
      3. A Point Type is validated against the range of all possible values for geographic coordinates: -90 to +90 for latitude and -180 to +180 for longitude. The service only provides hazard data for the state of subscribed states, however, and requests for valid coordinates outside subscribed states will return as “No Data.”
    3. A “BasicAddress” Type may include any of the following elements:
      1. address – REQUIRED: an un-parsed, free-text expression describing the requested location
      2. city – OPTIONAL: a City name (if not already included in “address”)
      3. state – OPTIONAL: a 2-character state code (if not already included in “address”)
      4. zip – OPTIONAL: a 5+ digit zip code (if not already included in “address”)
      5. A BasicAddress element must include an “address” element, which may include city, state and zip OR city, state and zip may be provided individually.
  2. RESPONSE
    1. The HazardResponse message body will include the following elements:
      1. status – ALWAYS: a “Result” enumeration value (See 3.1)
      2. message – omitted if status = SUCCESS; error description if status = FAILURE
      3. rzriskResult – an RZRiskResult Type if status = SUCCESS; omitted if status = FAILURE
      4. geoResult – an GeoResult Type if status = SUCCESS and “location” is a BasicAddress Type; omitted if status = FAILURE or “location” is a Point Type
    2. An “RZRiskResult” Type includes the following elements:
      1. zoneHazard – ALWAYS: a ZoneHazard Enumeration value (See 3.2)
      2. siteHazard – ALWAYS: a SiteHazard Enumeration value (See 3.3)
      3. distToSeverityZone – ALWAYS: the distance in miles from the nearest Zone of higher hazard
      4. nearbyFires – ALWAYS: a NearbyFires Type
      5. NOTE: Only Zones of higher hazard within 20 miles are considered when computing the distToSeverityZone value.
    3. A “NearbyFires” Type includes the following elements:
      1. count – ALWAYS: the total number of historical wildfire perimeters found within 10 miles
      2. avgSize – ZERO or ONE: the average size of all historical wildfire perimeters found
      3. avgDistance – ZERO or ONE: the average distance from of all historical wildfire perimeters found nearbyFire – ZERO or MORE: array of “NearbyFire” Types (See 2.4)
    4. A “NearbyFire” Type includes the following elements:
      1. distance – ALWAYS: the distance in miles from the historical wildfire perimeter
      2. fireYear – ALWAYS: the year in which the historical wildfire was contained
      3. fireName – ALWAYS: the name of the historical wildfire
      4. acres – ALWAYS: the size of the historical wildfire perimeter
      5. NOTE: Over a century of historical wildfire data is available. All are included in the NearbyFire element array to permit further analysis by the client.
    5. A “GeoResult” Type includes the following elements:
      1. geoPrecision – ALWAYS: a ZoneHazard Enumeration value (See 3.4)
      2. geoScore – ALWAYS: a ZoneHazard Enumeration value (See 3.5)
      3. point – ALWAYS: a Point Type (latitude and longitude – See 1.2)
      4. address – ALWAYS: a BasicAddress Type (See 1.3)
      5. A GeoResult is only provided in response to BassicAddress requests. This result is obtained from RedZone’s GeoAnalysis™ system which selects the “best” result from multiple geocoding services by assessing both address match quality and spatial distribution. The geoPrecision value reflects the HOW this best result was obtained (by on-site GPS, parcel data search, address interpolation, etc.) and the geoScore value indicates its probable correctness. The address element provides the address expression associated with the point as obtained from the underlying geocoding source.

 

Response Enumerations

All values defined as an enumeration value are returned as text as shown below. These enumerations list all possible responses:

  1. Result Enumeration
    1. SUCCESS
    2. FAILURE
  2. ZoneHazard Enumeration
    1. VERY_HIGH
    2. HIGH
    3. MODERATE
    4. NON-WILDLAND/NON-URBAN
    5. URBAN_UNZONED
    6. NO_DATA
  3. SiteHazard Enumeration
    1. EXTREME
    2. VERY_HIGH
    3. HIGH
    4. NO_THREAT
    5. NO_DATA
  4. GeoPrecision Enumeration
    1. ROOFTOP – centroid of a specific structure
    2. PARCEL – centroid of a property parcel
    3. INTERSECTION – intersection of two roads (or other linear features)
    4. LANDMARK – named place: public building, facility, landmark, etc.
    5. ADDRESS – position along a road segment as estimated from an address number
  5. GeoScore Enumeration
    1. GOOD
    2. REASONABLE
    3. SUSPECT
    4. PROBLEMATIC
    5. BAD
    6. UNKNOWN
  6. ErrorMsg Enumeration
    1. INVALID_LOGIN
    2. INVALID_REQUEST
    3. INVALID_LOCATION
    4. INVALID_POINT
    5. INVALID_ADDRESS
    6. ADDRESS_NOT_FOUND
    7. UNEXPECTED_ERROR
Was this article helpful to you? Yes No