Skip to main content

Risk Reporting

This use case shows how to generate detailed risk assessment reports for properties.

Using Python?

The Python SDK wraps risk endpoints in a typed client — client.risk.point_risk(payload) returns PDF bytes directly.

Scenario​

Generate risk reports for:

  • Individual properties (point risk)
  • Properties with surrounding area analysis (point-buffer risk)
  • Create PDF or HTML reports for stakeholders

Point Risk Report​

Generate a risk report for a single location:

{
  "point": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "layers": {
    "names": ["flood_risk", "seismic_risk", "environmental"],
    "source": "portfolio_01"
  },
  "map": {
    "baseLayer": "OpenStreetMap",
    "baseLayerType": "tile",
    "zoom": 14
  },
  "author": "John Smith"
}

Output formats:

  • application/pdf - PDF document
  • text/html - HTML document

Response:

[Binary PDF or HTML data]

Point-Buffer Risk Report​

Analyze risk with surrounding area context using concentric buffers:

{
  "point": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "buffer": {
    "radiuses": [1000, 5000],
    "style": "circle"
  },
  "layers": {
    "names": ["flood_risk", "seismic_risk", "environmental"],
    "source": "portfolio_01"
  },
  "filters": [
    {"field": "property_type", "value": "residential"}
  ],
  "aggregationColumns": ["risk_score", "mitigation_cost"],
  "map": {
    "baseLayer": "OpenStreetMap",
    "baseLayerType": "tile",
    "zoom": 14
  },
  "enhanced": [],
  "author": "John Smith",
  "locale": "en-US"
}

Code Examples​

Generate PDF Report (JavaScript)​

async function generateRiskReportPDF(lat, lon, reportName) {
  const apiKey = process.env.QARTA_API_KEY;

  const requestBody = {
    point: {
      type: "Point",
      coordinates: [lon, lat]
    },
    layers: {
      names: ["flood_risk", "seismic_risk", "environmental"],
      source: "portfolio_01"
    },
    map: {
      baseLayer: "OpenStreetMap",
      baseLayerType: "tile",
      zoom: 14
    },
    author: "Risk Team"
  };

  const response = await fetch(
    'https://graph.quarticle.ro/graph/api/v1/reports/risk/point',
    {
      method: 'POST',
      headers: {
        'Authorization': `${apiKey}`,
        'Content-Type': 'application/json',
        'Accept': 'application/pdf'
      },
      body: JSON.stringify(requestBody)
    }
  );

  // Get PDF as Buffer
  const pdfBuffer = await response.buffer();

  // Save to file
  const fs = require('fs');
  fs.writeFileSync(`${reportName}.pdf`, pdfBuffer);

  console.log(`Report saved: ${reportName}.pdf`);
}

// Usage
await generateRiskReportPDF(40.7128, -74.0060, 'property_123_risk_report');

Generate HTML Report (Python)​

import requests
import json

def generate_risk_report_html(lat, lon, output_file):
    api_key = os.getenv('QARTA_API_KEY')

    request_body = {
        'point': {
            'type': 'Point',
            'coordinates': [lon, lat]
        },
        'layers': {
            'names': ['flood_risk', 'seismic_risk', 'environmental'],
            'source': 'portfolio_01'
        },
        'map': {
            'baseLayer': 'OpenStreetMap',
            'baseLayerType': 'tile',
            'zoom': 14
        },
        'author': 'Risk Team'
    }

    response = requests.post(
        'https://graph.quarticle.ro/graph/api/v1/reports/risk/point',
        headers={
            'Authorization': f'{api_key}',
            'Content-Type': 'application/json',
            'Accept': 'text/html'
        },
        json=request_body
    )

    # Save HTML
    with open(output_file, 'w') as f:
        f.write(response.text)

    print(f'Report saved: {output_file}')

# Usage
generate_risk_report_html(40.7128, -74.0060, 'property_risk_report.html')

Batch Risk Reports​

Generate multiple reports programmatically:

async function generateBatchRiskReports(properties) {
  const apiKey = process.env.QARTA_API_KEY;
  const reports = [];

  for (const property of properties) {
    console.log(`Generating report for ${property.name}...`);

    const requestBody = {
      point: {
        type: "Point",
        coordinates: [property.lon, property.lat]
      },
      layers: {
        names: ["flood_risk", "seismic_risk"],
        source: "portfolio_01"
      },
      map: {
        baseLayer: "OpenStreetMap",
        baseLayerType: "tile",
        zoom: 14
      },
      author: "Risk Team"
    };

    const response = await fetch(
      'https://graph.quarticle.ro/graph/api/v1/reports/risk/point',
      {
        method: 'POST',
        headers: {
          'Authorization': `${apiKey}`,
          'Content-Type': 'application/json',
          'Accept': 'application/pdf'
        },
        body: JSON.stringify(requestBody)
      }
    );

    const pdfBuffer = await response.buffer();
    const fs = require('fs');
    const filename = `reports/${property.id}_risk_report.pdf`;
    fs.writeFileSync(filename, pdfBuffer);

    reports.push({
      property: property.name,
      file: filename,
      timestamp: new Date().toISOString()
    });
  }

  return reports;
}

V2 Risk Reports​

V2 endpoints support enhanced nested filters and V2 data models. Use /graph/api/v2/reports/risk/ endpoints instead of v1.

Difference: V2 accepts filters_v2 instead of filters:

{
  "filters_v2": [
    {
      "field": "property_type",
      "value": "residential",
      "filters": [
        {"field": "occupancy", "value": "occupied"}
      ]
    }
  ]
}

Report Content​

Reports typically include:

  • Risk Summary - Overall risk score and classifications
  • Environmental Risks - Flood, seismic, contamination, etc.
  • Map Visualization - Location on map with risk zones
  • Detailed Analysis - Data tables and metrics
  • Recommendations - Mitigation strategies
  • Historical Data - Trends and patterns

Use Cases​

  • Pre-acquisition due diligence - Evaluate risks before purchase
  • Insurance underwriting - Generate reports for insurers
  • Investor communications - Share risk profiles with stakeholders
  • Portfolio monitoring - Regular risk assessments
  • Regulatory compliance - Document risk assessments for audits

Error Handling​

try {
  const response = await fetch(
    'https://graph.quarticle.ro/graph/api/v1/reports/risk/point',
    { method: 'POST', ...options }
  );

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error: ${error.errorMessage.message}`);
    return null;
  }

  return await response.buffer();

} catch (error) {
  console.error('Report generation failed:', error);
  return null;
}

Next Steps​