geneva-forecast 1.0.1

Python SDK for the Geneva Forecasting Engine API

Geneva Forecast

Time-Series Forecasting & Demand Planning API
Powered by the Geneva Forecasting Engine, by RoadMap Technologies

---

Geneva Forecast is the official Python SDK for the Geneva Forecasting Engine: a high-performance time series API with automated model selection, conformal prediction intervals, and built-in chart generation. Forecast any time series in 3 lines of Python.

Forecast any time series with a single function call: model selection, accuracy metrics, and prediction intervals included.

---

Why Geneva Forecast?

Free to Get Started, No Credit Card Required

The Geneva API is free with 1,000 forecasts per month. Sign up at the Developer Portal, generate your API key, and start forecasting in minutes. No trial periods, no paywalls, no surprises.

---

Automated Model Selection

The Geneva Expert System evaluates all 10 forecasting methods against your data (exponential smoothing, Holt-Winters, regression curves, Croston) and selects the best fit automatically. Every result includes real accuracy metrics (MAD, MAPE, RMSE) and calibrated prediction intervals.

---

Built-In Visualization

Generate a professional forecast chart with a single function call: historical data, forecast line, and shaded prediction interval bands, with optional calendar date labels and file export. No extra dependencies required.

Example output from plot_forecast(): historical data, forecast line, and confidence interval bands

---

Requirements

Requirement	Details
Python	3.9 or later
API Key	Free, sign up at portal.roadmap-tech.com

Security: Your API key should be stored as an environment variable, never hardcoded in source files.

---

Installation

pip install geneva-forecast

---

Quick Start

from geneva_forecast import GenevaClient

client = GenevaClient(
    api_url="https://api.roadmap-tech.com",
    api_key="gva_your_api_key_here",
)

# Monthly sales data (6 years)
monthly_sales = [
    112.0, 118.4, 132.1, 124.3, 121.1, 140.2,
    148.9, 153.7, 136.2, 119.0, 104.0, 118.5,
    121.3, 129.8, 138.5, 146.7, 128.4, 155.3,
    162.8, 149.1, 141.7, 119.5, 108.2, 126.3,
    133.9, 142.7, 156.1, 137.8, 145.2, 161.4,
    178.3, 168.0, 149.5, 125.3, 113.7, 132.8,
    139.5, 155.8, 148.2, 163.4, 152.7, 175.9,
    194.1, 181.3, 162.8, 140.6, 129.3, 148.7,
    157.2, 149.8, 171.6, 158.3, 168.9, 189.4,
    210.7, 195.2, 174.3, 153.1, 141.8, 163.9,
    172.4, 181.9, 195.7, 178.3, 183.5, 204.6,
    226.3, 213.8, 188.7, 165.4, 155.2, 179.8,
]

result = client.forecast(
    data=monthly_sales,
    horizon=12,
    wave_periods=[12],
)

for point in result.forecast:
    print(f"  Period {point.period}: {point.value:.2f}")

print(f"Model: {result.model_info.method_name}")
print(f"MAPE:  {result.metrics.mape:.2f}%")

The client can also be used as a context manager:

with GenevaClient(api_url="https://api.roadmap-tech.com", api_key="gva_...") as client:
    result = client.forecast(data=monthly_sales, horizon=12)

---

Prediction Intervals

Get conformal prediction intervals by setting confidence_level:

result = client.forecast(
    data=monthly_sales,
    horizon=12,
    confidence_level=0.95,
    include=["forecast", "prediction_intervals", "metrics", "model_info"],
)

for pt in result.prediction_intervals:
    print(f"  Period {pt.period}: {pt.forecast:.2f}  [{pt.lower:.2f}, {pt.upper:.2f}]")

---

Batch Forecasting

Forecast multiple time series in a single request:

result = client.batch_forecast(series=[
    {
        "id": "product_a",
        "data": [100, 120, 115, 130, 125, 140, 135, 150, 145, 160, 155, 170],
        "horizon": 6,
    },
    {
        "id": "product_b",
        "data": [200, 210, 205, 220, 215, 230, 225, 240, 235, 250, 245, 260],
        "horizon": 6,
    },
])

print(f"Batch: {result.successful}/{result.total_series} succeeded in {result.elapsed_ms:.0f}ms")

for sr in result.results:
    if sr.status == "success":
        values = [f"{p.value:.1f}" for p in sr.forecast.forecast]
        print(f"  {sr.id}: {', '.join(values)}")

---

Visualization

Built-in charting with no extra dependencies:

from geneva_forecast.plot import plot_forecast

result = client.forecast(
    data=monthly_sales,
    horizon=12,
    confidence_level=0.95,
    include=["forecast", "fitted", "prediction_intervals", "metrics", "model_info"],
)

# One-liner chart with historical data, fitted values, forecast, and prediction intervals
plot_forecast(monthly_sales, result)

# Calendar date labels on x-axis
plot_forecast(monthly_sales, result, start_date="2020-01-01", freq="MS")
# Supported frequencies: "MS" (monthly), "QS" (quarterly), "W" (weekly),
#                        "D" (daily), "H" (hourly), "YS" (yearly)

# Save to file
plot_forecast(monthly_sales, result, show=False, save="forecast.png")

---

Parameters

Parameter	Type	Default	Description
data	list[float]	required	Time series values (min 3, max 10,000)
method	int | None	None	Forecasting method (0–9). None = auto-select best
wave_periods	list[int]	[12]	Seasonal cycle lengths (e.g. [12] monthly, [52] weekly)
horizon	int | None	None	Number of periods ahead to forecast
confidence_level	float | None	None	Prediction interval confidence (e.g. 0.95)
include	list[str]	["forecast", "metrics", "model_info"]	Response sections to return

Available include Sections

"forecast" · "fitted" · "seasonal_factors" · "metrics" · "model_info" · "prediction_intervals" · "all"

Set method=None (the default) to let the Expert System automatically select the best-performing model for your data.

Forecasting Methods

ID	Method	Best For
0	Linear Regression	Steady linear growth or decline
1–5	Non-Linear Regression (5 curve types)	Exponential, s-curve, power trends
6	Simple Exponential Smoothing	Stable, level series
7	Double Exponential Smoothing (Holt)	Trending series without seasonality
8	Holt-Winters (Seasonal)	Trending + seasonal series
9	Croston (Intermittent Demand)	Sporadic, zero-inflated series

---

Error Handling

from geneva_forecast import GenevaAPIError, GenevaConnectionError, GenevaTimeoutError

try:
    result = client.forecast(data=[1.0, 2.0, 3.0])
except GenevaAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
except GenevaTimeoutError:
    print("Request timed out")
except GenevaConnectionError:
    print("Could not connect to the Geneva API")

---

Related Resources

Resource	Description
Geneva Developer Portal	Free API keys, usage dashboard, and account management
Geneva MCP Server	Forecast directly from Claude, ChatGPT, Cursor, and Windsurf
Geneva API Documentation	Full API reference, parameter guides, and examples

---

License

MIT License, Copyright 2026 RoadMap Technologies, Inc.