openapi: 3.1.0
info:
  title: Verisk Insurance Analytics Catastrophe Property API
  description: Verisk (formerly ISO) provides insurance risk scoring, actuarial data, and property analytics APIs for P&C insurance carriers. APIs deliver loss cost data, risk classification, catastrophe modeling, property data, claims analytics, and underwriting data services for insurance pricing, reserving, and exposure management.
  version: '1.0'
  contact:
    name: Verisk Support
    url: https://www.verisk.com/contact/
  license:
    name: Verisk Terms of Service
    url: https://www.verisk.com/terms-of-use/
servers:
- url: https://api.verisk.com/insurance/v1
  description: Verisk Insurance Analytics API
security:
- BearerAuth: []
- ApiKeyHeader: []
tags:
- name: Property
  description: Property risk data and analytics
paths:
  /property/risk/{propertyId}:
    get:
      operationId: getPropertyRisk
      summary: Verisk Get Property Risk Assessment
      description: Returns comprehensive risk data for a specific property including construction, occupancy, fire protection class, ISO rating, and hazard scores for fire, wind, hail, flood, and earthquake exposures.
      tags:
      - Property
      parameters:
      - name: propertyId
        in: path
        required: true
        description: Property identifier (address or ISO property ID)
        schema:
          type: string
        example: PROP-123456
      - name: includePerils
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - FIRE
            - WIND
            - HAIL
            - FLOOD
            - EARTHQUAKE
            - WILDFIRE
            - LIGHTNING
        description: Peril types to include in response
        example: []
      - name: asOfDate
        in: query
        schema:
          type: string
          format: date
        description: Historical risk assessment date
        example: '2025-03-15'
      responses:
        '200':
          description: Property risk assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyRisk'
              examples:
                GetPropertyRisk200Example:
                  summary: Default getPropertyRisk 200 response
                  x-microcks-default: true
                  value:
                    propertyId: PROP-123456
                    address:
                      street: 123 Main St
                      city: San Francisco
                      state: CA
                      zipCode: '94105'
                      country: US
                    coordinates:
                      latitude: 36.1699
                      longitude: -115.1398
                    construction:
                      yearBuilt: 2025
                      squareFootage: 100
                      stories: 100
                      constructionType: FRAME
                      roofType: FRAME
                      occupancyType: RESIDENTIAL
                      buildingCode: example-value
                    fireProtection:
                      ppcGrade: 4
                      splitCode: example-value
                      fireDistrictName: Sample Name
                      distanceToFireStation: 0.8
                      distanceToHydrant: 0.8
                      communityName: Sample Name
                      state: CA
                      lastSurveyDate: '2025-03-15'
                    perilScores: {}
                    lastUpdated: '2025-03-15'
        '401':
          description: Unauthorized
        '404':
          description: Property not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /property/lookup:
    post:
      operationId: lookupPropertyByAddress
      summary: Verisk Look Up Property by Address
      description: Resolves a street address to a property record and returns risk data. Supports geocoding to USGS coordinates and ISO property identification.
      tags:
      - Property
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressLookupRequest'
            examples:
              LookupPropertyByAddressRequestExample:
                summary: Default lookupPropertyByAddress request
                x-microcks-default: true
                value:
                  streetAddress: 123 Main St
                  city: San Francisco
                  state: CA
                  zipCode: '94105'
                  includeRiskData: true
                  includePerils: []
      responses:
        '200':
          description: Property lookup result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyLookupResponse'
              examples:
                LookupPropertyByAddress200Example:
                  summary: Default lookupPropertyByAddress 200 response
                  x-microcks-default: true
                  value:
                    matchQuality: EXACT
                    propertyId: PROP-123456
                    address:
                      street: 123 Main St
                      city: San Francisco
                      state: CA
                      zipCode: '94105'
                      country: US
                    coordinates:
                      latitude: 36.1699
                      longitude: -115.1398
                    riskData:
                      propertyId: PROP-123456
                      address:
                        street: 123 Main St
                        city: San Francisco
                        state: CA
                        zipCode: '94105'
                        country: US
                      coordinates:
                        latitude: 36.1699
                        longitude: -115.1398
                      construction:
                        yearBuilt: 2025
                        squareFootage: 100
                        stories: 100
                        constructionType: FRAME
                        roofType: FRAME
                        occupancyType: RESIDENTIAL
                        buildingCode: example-value
                      fireProtection:
                        ppcGrade: 4
                        splitCode: example-value
                        fireDistrictName: Sample Name
                        distanceToFireStation: 0.8
                        distanceToHydrant: 0.8
                        communityName: Sample Name
                        state: CA
                        lastSurveyDate: '2025-03-15'
                      perilScores: {}
                      lastUpdated: '2025-03-15'
        '400':
          description: Invalid address format
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PropertyLookupResponse:
      type: object
      properties:
        matchQuality:
          type: string
          enum:
          - EXACT
          - INTERPOLATED
          - ZIP_CENTROID
          - CITY_CENTROID
          example: EXACT
        propertyId:
          type: string
          example: PROP-123456
        address:
          $ref: '#/components/schemas/Address'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        riskData:
          $ref: '#/components/schemas/PropertyRisk'
    ConstructionData:
      type: object
      properties:
        yearBuilt:
          type: integer
          example: 2025
        squareFootage:
          type: integer
          example: 100
        stories:
          type: integer
          example: 100
        constructionType:
          type: string
          enum:
          - FRAME
          - MASONRY
          - FIRE_RESISTIVE
          - MODIFIED_FIRE_RESISTIVE
          - JOISTED_MASONRY
          - NON_COMBUSTIBLE
          example: FRAME
        roofType:
          type: string
          example: FRAME
        occupancyType:
          type: string
          enum:
          - RESIDENTIAL
          - COMMERCIAL
          - INDUSTRIAL
          - MIXED_USE
          example: RESIDENTIAL
        buildingCode:
          type: string
          description: Applicable building code version
          example: example-value
    FireProtectionClass:
      type: object
      properties:
        ppcGrade:
          type: integer
          minimum: 1
          maximum: 10
          description: ISO Public Protection Classification grade
          example: 4
        splitCode:
          type: string
          description: Split code (e.g., 4/9 for split classification)
          example: example-value
        fireDistrictName:
          type: string
          example: Sample Name
        distanceToFireStation:
          type: number
          description: Distance to nearest responding fire station in miles
          example: 0.8
        distanceToHydrant:
          type: number
          description: Distance to nearest fire hydrant in feet
          example: 0.8
        communityName:
          type: string
          example: Sample Name
        state:
          type: string
          example: CA
        lastSurveyDate:
          type: string
          format: date
          example: '2025-03-15'
    AddressLookupRequest:
      type: object
      required:
      - streetAddress
      - city
      - state
      properties:
        streetAddress:
          type: string
          example: 123 Main St
        city:
          type: string
          example: San Francisco
        state:
          type: string
          pattern: ^[A-Z]{2}$
          example: CA
        zipCode:
          type: string
          example: '94105'
        includeRiskData:
          type: boolean
          default: true
          example: true
        includePerils:
          type: array
          items:
            type: string
          example: []
    Address:
      type: object
      properties:
        street:
          type: string
          example: 123 Main St
        city:
          type: string
          example: San Francisco
        state:
          type: string
          pattern: ^[A-Z]{2}$
          example: CA
        zipCode:
          type: string
          example: '94105'
        country:
          type: string
          default: US
          example: US
    Coordinates:
      type: object
      properties:
        latitude:
          type: number
          minimum: -90
          maximum: 90
          example: 36.1699
        longitude:
          type: number
          minimum: -180
          maximum: 180
          example: -115.1398
    PropertyRisk:
      type: object
      properties:
        propertyId:
          type: string
          example: PROP-123456
        address:
          $ref: '#/components/schemas/Address'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        construction:
          $ref: '#/components/schemas/ConstructionData'
        fireProtection:
          $ref: '#/components/schemas/FireProtectionClass'
        perilScores:
          type: object
          additionalProperties:
            type: object
            properties:
              score:
                type: integer
                minimum: 1
                maximum: 100
              riskCategory:
                type: string
                enum:
                - VERY_LOW
                - LOW
                - MODERATE
                - HIGH
                - VERY_HIGH
                - EXTREME
              description:
                type: string
          example: {}
        lastUpdated:
          type: string
          format: date
          example: '2025-03-15'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key