API Reference

Insights Endpoints

Insights Endpoints

The insights endpoints provide access to Spartera's core analytics
capabilities. These endpoints allow you to execute analytical queries,
retrieve processed insights, and access business intelligence
visualizations without exposing underlying data.

Core Analytics Execution

Execute Company Analysis

Generate comprehensive insights about a company using available data
sources and analytical models.

POST /insights/companies/{company_handle}/analyze

Execute Company Analysis Parameters

  • company_handle (path, required): Unique identifier or handle for
    the target company

Execute Company Analysis Request Body

{
  "analysis_type": "comprehensive",
  "metrics": [
    "financial_health",
    "market_position",
    "growth_trends",
    "risk_assessment"
  ],
  "time_range": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  },
  "filters": {
    "industry": "technology",
    "market_cap_range": "large"
  },
  "output_format": "detailed"
}

Execute Company Analysis Response

{
  "data": {
    "company_handle": "example-corp",
    "analysis_id": "analysis_12345",
    "generated_at": "2025-01-20T15:30:00Z",
    "insights": {
      "financial_health": {
        "score": 8.5,
        "rating": "strong",
        "key_indicators": {
          "revenue_growth": "12.5%",
          "profit_margin": "18.2%",
          "debt_ratio": "0.35"
        }
      },
      "market_position": {
        "rank": 3,
        "market_share": "15.8%",
        "competitive_advantage": "high"
      },
      "growth_trends": {
        "trajectory": "positive",
        "projected_growth": "8.2%",
        "confidence": 0.87
      },
      "risk_assessment": {
        "overall_risk": "moderate",
        "risk_factors": [
          "market_volatility",
          "regulatory_changes"
        ]
      }
    },
    "metadata": {
      "data_sources": 15,
      "processing_time_ms": 2450,
      "confidence_level": 0.91
    }
  }
}

Get Historical Insights

Retrieve previously generated insights for a company or entity.

GET /insights/companies/{company_handle}/history

Get Historical Insights Parameters

  • company_handle (path, required): Company identifier

Get Historical Insights Query Parameters

  • limit (optional): Number of historical insights to return (default: 50)
  • offset (optional): Pagination offset (default: 0)
  • analysis_type (optional): Filter by specific analysis type
  • start_date (optional): Filter insights from this date
  • end_date (optional): Filter insights up to this date

Get Historical Insights Response

{
  "data": [
    {
      "analysis_id": "analysis_12345",
      "generated_at": "2025-01-20T15:30:00Z",
      "analysis_type": "comprehensive",
      "summary": {
        "financial_health": 8.5,
        "market_position": 7.8,
        "growth_potential": 8.1
      },
      "status": "completed"
    }
  ],
  "meta": {
    "total": 127,
    "page": 1,
    "per_page": 50
  }
}

Get Specific Insight

Retrieve detailed results for a specific analysis.

GET /insights/analyses/{analysis_id}

Get Specific Insight Parameters

  • analysis_id (path, required): Unique identifier for the analysis

Get Specific Insight Response

{
  "data": {
    "analysis_id": "analysis_12345",
    "company_handle": "example-corp",
    "analysis_type": "comprehensive",
    "status": "completed",
    "generated_at": "2025-01-20T15:30:00Z",
    "insights": {
      "executive_summary": "Strong financial performance with...",
      "detailed_metrics": {},
      "recommendations": [
        "Expand market presence in emerging sectors",
        "Optimize operational efficiency"
      ],
      "risk_mitigation": [
        "Diversify revenue streams",
        "Strengthen regulatory compliance"
      ]
    },
    "visualizations": {
      "financial_trends": {
        "chart_type": "line",
        "data_url": "/insights/analyses/analysis_12345/charts/financial_trends"
      },
      "market_comparison": {
        "chart_type": "bar",
        "data_url": "/insights/analyses/analysis_12345/charts/market_comparison"
      }
    }
  }
}

Real-Time Analytics

Stream Live Insights

Access real-time analytical insights as they become available.

GET /insights/stream/{company_handle}

Stream Live Insights Parameters

  • company_handle (path, required): Company identifier

Stream Live Insights Query Parameters

  • metrics (optional): Comma-separated list of specific metrics
  • update_frequency (optional): Update interval (1m, 5m, 15m, 1h)

Stream Live Insights Response (Server-Sent Events)

data: {"metric": "stock_price", "value": 125.67, "change": "+2.3%", "timestamp": "2025-01-20T15:35:00Z"}

data: {"metric": "social_sentiment", "value": 0.75, "change": "+0.05", "timestamp": "2025-01-20T15:35:00Z"}

Real-Time Market Intelligence

Get live market intelligence and competitive positioning data.

POST /insights/market/realtime

Real-Time Market Intelligence Request Body

{
  "companies": ["company-a", "company-b", "company-c"],
  "metrics": [
    "market_share",
    "sentiment_score",
    "performance_index"
  ],
  "comparison_type": "relative"
}

Real-Time Market Intelligence Response

{
  "data": {
    "generated_at": "2025-01-20T15:30:00Z",
    "market_snapshot": {
      "company-a": {
        "market_share": 25.3,
        "sentiment_score": 0.78,
        "performance_index": 112.5
      },
      "company-b": {
        "market_share": 18.7,
        "sentiment_score": 0.65,
        "performance_index": 98.2
      }
    },
    "trends": {
      "market_direction": "positive",
      "volatility": "moderate",
      "key_drivers": ["earnings_growth", "market_expansion"]
    }
  }
}

Predictive Analytics

Forecast Generation

Generate predictive insights and forecasts based on historical data
and market trends.

POST /insights/forecast

Forecast Generation Request Body

{
  "entity_id": "company-123",
  "forecast_type": "revenue",
  "time_horizon": "12_months",
  "confidence_intervals": [0.80, 0.95],
  "include_scenarios": ["optimistic", "realistic", "pessimistic"],
  "external_factors": [
    "market_conditions",
    "economic_indicators",
    "industry_trends"
  ]
}

Forecast Generation Response

{
  "data": {
    "forecast_id": "forecast_789",
    "entity_id": "company-123",
    "forecast_type": "revenue",
    "generated_at": "2025-01-20T15:30:00Z",
    "predictions": {
      "realistic": [
        {"period": "2025-02", "value": 125000000, "confidence": 0.85},
        {"period": "2025-03", "value": 132000000, "confidence": 0.83}
      ],
      "optimistic": [
        {"period": "2025-02", "value": 140000000, "confidence": 0.65},
        {"period": "2025-03", "value": 148000000, "confidence": 0.62}
      ],
      "pessimistic": [
        {"period": "2025-02", "value": 110000000, "confidence": 0.75},
        {"period": "2025-03", "value": 115000000, "confidence": 0.73}
      ]
    },
    "key_assumptions": [
      "Market growth continues at current rate",
      "No major regulatory changes",
      "Competitive landscape remains stable"
    ]
  }
}

Trend Analysis

Analyze trends and patterns in data over specified time periods.

POST /insights/trends/analyze

Trend Analysis Request Body

{
  "data_source": "company_metrics",
  "entity_id": "company-123",
  "metrics": ["revenue", "market_share", "customer_satisfaction"],
  "time_range": {
    "start_date": "2023-01-01",
    "end_date": "2024-12-31"
  },
  "trend_types": ["seasonal", "linear", "cyclical"],
  "granularity": "monthly"
}

Trend Analysis Response

{
  "data": {
    "analysis_id": "trend_456",
    "entity_id": "company-123",
    "trends": {
      "revenue": {
        "overall_trend": "increasing",
        "trend_strength": 0.78,
        "seasonal_pattern": "Q4_peak",
        "growth_rate": "8.5%_annually",
        "anomalies": [
          {
            "period": "2024-03",
            "type": "spike",
            "magnitude": 1.25
          }
        ]
      },
      "market_share": {
        "overall_trend": "stable",
        "trend_strength": 0.45,
        "volatility": "low",
        "correlation_with_revenue": 0.67
      }
    },
    "insights": [
      "Strong revenue growth with consistent Q4 performance peaks",
      "Market share stability indicates strong competitive position"
    ]
  }
}

Data Visualization

Generate Charts

Create visual representations of analytical insights.

GET /insights/analyses/{analysis_id}/charts/{chart_type}

Generate Charts Parameters

  • analysis_id (path, required): Analysis identifier
  • chart_type (path, required): Type of chart (financial_trends,
    market_comparison, risk_matrix, etc.)

Generate Charts Query Parameters

  • format (optional): Output format (png, svg, json, default: json)
  • width (optional): Chart width in pixels (default: 800)
  • height (optional): Chart height in pixels (default: 600)
  • theme (optional): Visual theme (light, dark, default: light)

Generate Charts Response (JSON format)

{
  "data": {
    "chart_id": "chart_789",
    "chart_type": "financial_trends",
    "config": {
      "type": "line",
      "data": {
        "labels": ["Q1 2024", "Q2 2024", "Q3 2024", "Q4 2024"],
        "datasets": [
          {
            "label": "Revenue",
            "data": [125, 132, 145, 158],
            "borderColor": "#4CAF50"
          }
        ]
      },
      "options": {
        "responsive": true,
        "title": {
          "display": true,
          "text": "Revenue Trends - 2024"
        }
      }
    }
  }
}

Export Insights

Export analytical insights in various formats for external use.

POST /insights/analyses/{analysis_id}/export

Export Insights Parameters

  • analysis_id (path, required): Analysis identifier

Export Insights Request Body

{
  "format": "pdf",
  "sections": [
    "executive_summary",
    "detailed_analysis",
    "recommendations",
    "visualizations"
  ],
  "customization": {
    "company_branding": true,
    "include_raw_data": false,
    "chart_style": "professional"
  }
}

Export Insights Response

{
  "data": {
    "export_id": "export_123",
    "status": "processing",
    "estimated_completion": "2025-01-20T15:35:00Z",
    "download_url": null
  }
}

Error Handling

Common Insight Errors

  • 400 Bad Request: Invalid analysis parameters
  • 404 Not Found: Company or analysis not found
  • 422 Unprocessable Entity: Insufficient data for analysis
  • 429 Too Many Requests: Rate limit exceeded
  • 503 Service Unavailable: Analysis service temporarily unavailable

Example Error Response

{
  "error": {
    "code": "INSUFFICIENT_DATA",
    "message": "Not enough data available to generate reliable insights",
    "details": {
      "company_handle": "example-corp",
      "required_data_points": 100,
      "available_data_points": 45
    }
  }
}

The insights endpoints provide powerful analytical capabilities while
maintaining data privacy and security. Use these endpoints to generate
actionable business intelligence from your connected data sources.