openapi: 3.1.0
info:
  title: Verisk Insurance Analytics 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: Catastrophe
  description: Catastrophe modeling and peril data
- name: Claims
  description: Claims analytics and benchmarking
- name: Property
  description: Property risk data and analytics
- name: Risk Scoring
  description: Insurance risk scores and rating factors
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
  /risk/scores:
    post:
      operationId: getRiskScores
      summary: Verisk Get Insurance Risk Scores
      description: >-
        Returns risk scores for properties, policies, or portfolios. Includes
        ISO fire protection classification, building code effectiveness grading,
        and commercial/personal lines risk scores.
      tags:
      - Risk Scoring
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskScoreRequest'
            examples:
              GetRiskScoresRequestExample:
                summary: Default getRiskScores request
                x-microcks-default: true
                value:
                  locations: []
                  scoreTypes: []
      responses:
        '200':
          description: Risk scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskScoreResponse'

              examples:
                GetRiskScores200Example:
                  summary: Default getRiskScores 200 response
                  x-microcks-default: true
                  value:
                    locations: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /risk/fire-protection-class:
    get:
      operationId: getFireProtectionClass
      summary: Verisk Get ISO Fire Protection Class (PPC)
      description: >-
        Returns the ISO Public Protection Classification (PPC) grade for a
        location, which measures a community's fire suppression capability.
        PPC grades range from 1 (best) to 10.
      tags:
      - Risk Scoring
      parameters:
      - name: latitude
        in: query
        required: true
        schema:
          type: number
        example: 36.1699
      - name: longitude
        in: query
        required: true
        schema:
          type: number
        example: -115.1398
      - name: constructionType
        in: query
        schema:
          type: string
          enum: [FRAME, MASONRY, FIRE_RESISTIVE, MODIFIED_FIRE_RESISTIVE, JOISTED_MASONRY, NON_COMBUSTIBLE]
        description: ISO construction class
        example: FRAME
      responses:
        '200':
          description: Fire protection class data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FireProtectionClass'

              examples:
                GetFireProtectionClass200Example:
                  summary: Default getFireProtectionClass 200 response
                  x-microcks-default: true
                  value:
                    ppcGrade: 4
                    splitCode: example-value
                    fireDistrictName: Sample Name
                    distanceToFireStation: 0.8
                    distanceToHydrant: 0.8
                    communityName: Sample Name
                    state: CA
                    lastSurveyDate: '2025-03-15'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catastrophe/peril-scores:
    post:
      operationId: getPerilScores
      summary: Verisk Get Catastrophe Peril Scores
      description: >-
        Returns catastrophe exposure scores for natural hazard perils including
        hurricane, tornado, hail, wildfire, earthquake, and flood for a list
        of locations. Used for catastrophe risk management and PML estimation.
      tags:
      - Catastrophe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PerilScoreRequest'
            examples:
              GetPerilScoresRequestExample:
                summary: Default getPerilScores request
                x-microcks-default: true
                value:
                  locations: []
                  perils: []
      responses:
        '200':
          description: Peril exposure scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerilScoreResponse'

              examples:
                GetPerilScores200Example:
                  summary: Default getPerilScores 200 response
                  x-microcks-default: true
                  value:
                    locations: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /claims/benchmarks:
    get:
      operationId: getClaimsBenchmarks
      summary: Verisk Get Claims Benchmarking Data
      description: >-
        Returns industry claims benchmarking data for loss frequency, loss severity,
        and combined ratio metrics across lines of business, states, and risk segments.
      tags:
      - Claims
      parameters:
      - name: lineOfBusiness
        in: query
        required: true
        schema:
          type: string
          enum: [HOMEOWNERS, AUTO, COMMERCIAL_AUTO, CGL, COMMERCIAL_PROPERTY, WORKERS_COMP]
        example: HOMEOWNERS
      - name: state
        in: query
        required: false
        schema:
          type: string
          pattern: "^[A-Z]{2}$"
        description: US state code
        example: CA
      - name: year
        in: query
        schema:
          type: integer
          example: 2025
        example: 2025
      - name: metricType
        in: query
        schema:
          type: string
          enum: [FREQUENCY, SEVERITY, COMBINED_RATIO, LOSS_RATIO]
        example: FREQUENCY
      responses:
        '200':
          description: Claims benchmarking metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimsBenchmarks'

              examples:
                GetClaimsBenchmarks200Example:
                  summary: Default getClaimsBenchmarks 200 response
                  x-microcks-default: true
                  value:
                    lineOfBusiness: example-value
                    state: CA
                    year: 2025
                    metrics: {}
                    sampleSize: 100
                    source: Verisk ISO
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    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'
    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: []
    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'

    RiskScoreRequest:
      type: object
      required:
      - locations
      - scoreTypes
      properties:
        locations:
          type: array
          maxItems: 100
          items:
            type: object
            properties:
              locationId:
                type: string
              address:
                $ref: '#/components/schemas/Address'
              coordinates:
                $ref: '#/components/schemas/Coordinates'
          example: []
        scoreTypes:
          type: array
          items:
            type: string
            enum: [FIRE_PROTECTION_CLASS, BUILDING_CODE_EFFECTIVENESS, FLOOD_ZONE, EARTHQUAKE_ZONE, WIND_ZONE]
          example: []

    RiskScoreResponse:
      type: object
      properties:
        locations:
          type: array
          items:
            type: object
            properties:
              locationId:
                type: string
              scores:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    score:
                      oneOf:
                      - type: integer
                      - type: string
                      - type: number
                    description:
                      type: string

          example: []
    PerilScoreRequest:
      type: object
      required:
      - locations
      - perils
      properties:
        locations:
          type: array
          items:
            type: object
            properties:
              locationId:
                type: string
              latitude:
                type: number
              longitude:
                type: number
          example: []
        perils:
          type: array
          items:
            type: string
            enum: [HURRICANE, TORNADO, HAIL, WILDFIRE, EARTHQUAKE, FLOOD, WINTER_STORM, LIGHTNING]
          example: []

    PerilScoreResponse:
      type: object
      properties:
        locations:
          type: array
          items:
            type: object
            properties:
              locationId:
                type: string
              perils:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    score:
                      type: integer
                      minimum: 1
                      maximum: 100
                    riskTier:
                      type: string
                      enum: [TIER_1, TIER_2, TIER_3, TIER_4, TIER_5]
                    annualExceedanceProbability:
                      type: number
                      description: Annual probability of loss event

          example: []
    ClaimsBenchmarks:
      type: object
      properties:
        lineOfBusiness:
          type: string
          example: example-value
        state:
          type: string
          example: CA
        year:
          type: integer
          example: 2025
        metrics:
          type: object
          properties:
            frequency:
              type: number
              description: Claims frequency per 100 exposures
            averageSeverity:
              type: number
              description: Average claim severity in USD
            lossRatio:
              type: number
              description: Loss ratio as decimal (0.0-1.0+)
            combinedRatio:
              type: number
          example: {}
        sampleSize:
          type: integer
          description: Number of policies in benchmark sample
          example: 100
        source:
          type: string
          description: Data source and vintage

          example: Verisk ISO
    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