# The Forecasting Company Python SDK
[](https://pypi.org/project/theforecastingcompany/)
[](https://status.retrocast.com)
The python SDK provides a simple interface to make forecasts using the TFC API.
## Documentation
The REST API documentation can be found on [https://api.retrocast.com/docs](https://api.retrocast.com/docs).
To get an API key, visit the [Authentication docs](https://api.retrocast.com/docs/routes#authentication). In the **API Keys** section you will find an option to _Sign in_ or, if you already signed in, a box containing your API key.
## Installation
```sh
# install from PyPI
pip install theforecastingcompany
```
## Usage
```python
# By default it will look for api_key in os.getenv("TFC_API_KEY"). Otherwise you can explicity set the api_key argument
client = TFCClient()
# Compute forecast for a single model
timesfm_df = client.forecast(
train_df,
model=TFCModels.TimesFM_2 # StrEnum defined in utils. You can also pass the model name as a string, eg timesfm-2
horizon=12,
freq="W",
quantiles=[0.5,0.1,0.9]
)
# Global Model with static variables
tfc_global_df = client.forecast(
train_df,
model=TFCModels.TFCGlobal,
horizon=12,
freq="W",
static_variables=["unique_id","Group","Vendor","Category"],
add_holidays=True,
add_events=True,
country_isocode = "US",
# Fit a separate global model for each group.
# If None, a single global model is fitted to all timeseries.
partition_by=["Group"]
)
```
If future_variables are available, make sure to pass also a `future_df` when forecasting, and setting the `future_variables` argument. **Important**: The same `future_variables` columns must be present in both `train_df` and `future_df`. For example, if you specify `future_variables=["price", "promotion"]`, both columns must exist in the historical data (`train_df`) and in the future data (`future_df`).
The `cross_validate` function is basically the same, but takes a `fcds` argument to define the FCDs to use for cross-validation. It also returns the target column in the output dataframe.
### Data Structure Requirements
Both `train_df` and `future_df` must contain the following columns:
- **`unique_id`** (or custom `id_col`): Unique identifier for each time series
- **`ds`** (or custom `date_col`): Date/timestamp column (must be datetime format)
- **`target`** (or custom `target_col`): The values to forecast
You can customize column names using the `id_col`, `date_col`, and `target_col` parameters if your data uses different naming conventions.
**Example `train_df`** with historical data, static variables (`region`, `store_type`), and future variables (`price`, `promotion`):
```python
import pandas as pd
train_df = pd.DataFrame({
"unique_id": ["store_1", "store_1", "store_1", "store_2", "store_2", "store_2"],
"ds": pd.to_datetime(["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-01", "2024-01-02", "2024-01-03"]),
"target": [100, 105, 110, 200, 195, 205],
"region": ["North", "North", "North", "South", "South", "South"], # static variable
"store_type": ["Premium", "Premium", "Premium", "Standard", "Standard", "Standard"], # static variable
"price": [9.99, 9.99, 9.99, 12.99, 12.99, 12.99], # future variable (must be in train_df too!)
"promotion": [0, 1, 0, 1, 0, 1] # future variable (must be in train_df too!)
})
```
**Example `future_df`** with the same future variables `price` and `promotion`:
```python
future_df = pd.DataFrame({
"unique_id": ["store_1", "store_1", "store_2", "store_2"],
"ds": pd.to_datetime(["2024-01-04", "2024-01-05", "2024-01-04", "2024-01-05"]),
"price": [9.99, 8.99, 12.99, 11.99], # future variable
"promotion": [1, 0, 0, 1] # future variable
})
# Forecasting with future variables
forecast_df = client.forecast(
train_df,
future_df=future_df,
model=TFCModels.TFCGlobal,
horizon=2,
freq="D",
static_variables=["region", "store_type"],
future_variables=["price", "promotion"] # These columns must exist in both train_df and future_df
)
```
**Using custom column names**:
```python
# If your data uses different column names
my_data = pd.DataFrame({
"item_id": ["A", "A", "B", "B"],
"date": pd.to_datetime(["2024-01-01", "2024-01-02", "2024-01-01", "2024-01-02"]),
"sales": [50, 55, 30, 32]
})
forecast_df = client.forecast(
my_data,
model=TFCModels.TimesFM_2,
horizon=7,
freq="D",
id_col="item_id", # specify your ID column
date_col="date", # specify your date column
target_col="sales" # specify your target column
)
```
## Versioning
This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
1. Changes that only affect static types, without breaking runtime behavior.
2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
3. Changes that we do not expect to impact the vast majority of users in practice.
We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
We are keen for your feedback; please open an [issue](https://www.github.com/openai/openai-python/issues) with questions, bugs, or suggestions.
### Determining the installed version
If you've upgraded to the latest version but aren't seeing any new features you were expecting then your python environment is likely still using an older version.
You can determine the version that is being used at runtime with:
```py
import theforecastingcompany
print(theforecastingcompany.__version__)
```
## Requirements
Python 3.11 or higher.
Raw data
{
"_id": null,
"home_page": null,
"name": "theforecastingcompany",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "api, artificial-intelligence, data-science, deep-learning, forecasting, foundation-model, machine-learning, prediction, python-sdk, tfc, time-series, time-series-forecasting",
"author": null,
"author_email": "The Forecasting Company <support@theforecastingcompany.com>",
"download_url": "https://files.pythonhosted.org/packages/d9/d3/5afa25e24aea9bb5113181bed55f23675ede43731f3da28d967ab3bd401f/theforecastingcompany-0.2.2.tar.gz",
"platform": null,
"description": "# The Forecasting Company Python SDK\n\n[](https://pypi.org/project/theforecastingcompany/)\n[](https://status.retrocast.com)\n\nThe python SDK provides a simple interface to make forecasts using the TFC API.\n\n## Documentation\n\nThe REST API documentation can be found on [https://api.retrocast.com/docs](https://api.retrocast.com/docs).\n\nTo get an API key, visit the [Authentication docs](https://api.retrocast.com/docs/routes#authentication). In the **API Keys** section you will find an option to _Sign in_ or, if you already signed in, a box containing your API key.\n\n## Installation\n\n```sh\n# install from PyPI\npip install theforecastingcompany\n```\n\n## Usage\n\n```python\n# By default it will look for api_key in os.getenv(\"TFC_API_KEY\"). Otherwise you can explicity set the api_key argument\nclient = TFCClient()\n\n# Compute forecast for a single model\ntimesfm_df = client.forecast(\n train_df,\n model=TFCModels.TimesFM_2 # StrEnum defined in utils. You can also pass the model name as a string, eg timesfm-2\n horizon=12,\n freq=\"W\",\n quantiles=[0.5,0.1,0.9]\n)\n\n# Global Model with static variables\ntfc_global_df = client.forecast(\n train_df,\n model=TFCModels.TFCGlobal,\n horizon=12,\n freq=\"W\",\n static_variables=[\"unique_id\",\"Group\",\"Vendor\",\"Category\"],\n add_holidays=True,\n add_events=True,\n country_isocode = \"US\",\n # Fit a separate global model for each group.\n # If None, a single global model is fitted to all timeseries.\n partition_by=[\"Group\"]\n )\n```\n\nIf future_variables are available, make sure to pass also a `future_df` when forecasting, and setting the `future_variables` argument. **Important**: The same `future_variables` columns must be present in both `train_df` and `future_df`. For example, if you specify `future_variables=[\"price\", \"promotion\"]`, both columns must exist in the historical data (`train_df`) and in the future data (`future_df`).\n\nThe `cross_validate` function is basically the same, but takes a `fcds` argument to define the FCDs to use for cross-validation. It also returns the target column in the output dataframe. \n\n### Data Structure Requirements\n\nBoth `train_df` and `future_df` must contain the following columns:\n\n- **`unique_id`** (or custom `id_col`): Unique identifier for each time series\n- **`ds`** (or custom `date_col`): Date/timestamp column (must be datetime format)\n- **`target`** (or custom `target_col`): The values to forecast\n\nYou can customize column names using the `id_col`, `date_col`, and `target_col` parameters if your data uses different naming conventions.\n\n**Example `train_df`** with historical data, static variables (`region`, `store_type`), and future variables (`price`, `promotion`):\n\n```python\nimport pandas as pd\n\ntrain_df = pd.DataFrame({\n \"unique_id\": [\"store_1\", \"store_1\", \"store_1\", \"store_2\", \"store_2\", \"store_2\"],\n \"ds\": pd.to_datetime([\"2024-01-01\", \"2024-01-02\", \"2024-01-03\", \"2024-01-01\", \"2024-01-02\", \"2024-01-03\"]),\n \"target\": [100, 105, 110, 200, 195, 205],\n \"region\": [\"North\", \"North\", \"North\", \"South\", \"South\", \"South\"], # static variable\n \"store_type\": [\"Premium\", \"Premium\", \"Premium\", \"Standard\", \"Standard\", \"Standard\"], # static variable\n \"price\": [9.99, 9.99, 9.99, 12.99, 12.99, 12.99], # future variable (must be in train_df too!)\n \"promotion\": [0, 1, 0, 1, 0, 1] # future variable (must be in train_df too!)\n})\n```\n\n**Example `future_df`** with the same future variables `price` and `promotion`:\n\n```python\nfuture_df = pd.DataFrame({\n \"unique_id\": [\"store_1\", \"store_1\", \"store_2\", \"store_2\"],\n \"ds\": pd.to_datetime([\"2024-01-04\", \"2024-01-05\", \"2024-01-04\", \"2024-01-05\"]),\n \"price\": [9.99, 8.99, 12.99, 11.99], # future variable\n \"promotion\": [1, 0, 0, 1] # future variable\n})\n\n# Forecasting with future variables\nforecast_df = client.forecast(\n train_df,\n future_df=future_df,\n model=TFCModels.TFCGlobal,\n horizon=2,\n freq=\"D\",\n static_variables=[\"region\", \"store_type\"],\n future_variables=[\"price\", \"promotion\"] # These columns must exist in both train_df and future_df\n)\n```\n\n**Using custom column names**:\n\n```python\n# If your data uses different column names\nmy_data = pd.DataFrame({\n \"item_id\": [\"A\", \"A\", \"B\", \"B\"],\n \"date\": pd.to_datetime([\"2024-01-01\", \"2024-01-02\", \"2024-01-01\", \"2024-01-02\"]),\n \"sales\": [50, 55, 30, 32]\n})\n\nforecast_df = client.forecast(\n my_data,\n model=TFCModels.TimesFM_2,\n horizon=7,\n freq=\"D\",\n id_col=\"item_id\", # specify your ID column\n date_col=\"date\", # specify your date column\n target_col=\"sales\" # specify your target column\n)\n```\n\n## Versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/openai/openai-python/issues) with questions, bugs, or suggestions.\n\n### Determining the installed version\n\nIf you've upgraded to the latest version but aren't seeing any new features you were expecting then your python environment is likely still using an older version.\n\nYou can determine the version that is being used at runtime with:\n\n```py\nimport theforecastingcompany\nprint(theforecastingcompany.__version__)\n```\n\n## Requirements\n\nPython 3.11 or higher.\n",
"bugtrack_url": null,
"license": null,
"summary": "The official Python library for The Forecasting Company API",
"version": "0.2.2",
"project_urls": {
"docs": "https://api.retrocast.com/docs",
"homepage": "https://theforecastingcompany.com",
"repository": "https://github.com/theforecastingcompany/theforecastingcompany-sdk-python"
},
"split_keywords": [
"api",
" artificial-intelligence",
" data-science",
" deep-learning",
" forecasting",
" foundation-model",
" machine-learning",
" prediction",
" python-sdk",
" tfc",
" time-series",
" time-series-forecasting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06024988da1c548490f8794b2519c6cc4f3c5a53d414303b23c688c746d082b4",
"md5": "79d645fef8948d7bdc5faf529515122d",
"sha256": "5210af3c442e36ba6f85e19657fc1748aad0e8cfdbed8378c3d9dd72911ba19b"
},
"downloads": -1,
"filename": "theforecastingcompany-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79d645fef8948d7bdc5faf529515122d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 24270,
"upload_time": "2025-10-22T16:33:24",
"upload_time_iso_8601": "2025-10-22T16:33:24.367169Z",
"url": "https://files.pythonhosted.org/packages/06/02/4988da1c548490f8794b2519c6cc4f3c5a53d414303b23c688c746d082b4/theforecastingcompany-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d9d35afa25e24aea9bb5113181bed55f23675ede43731f3da28d967ab3bd401f",
"md5": "6d464ee539c246f79035d1f3478de365",
"sha256": "4e04c561303787e657e84dff4bf812e79af457be81bcedcaeb618eb7f071a054"
},
"downloads": -1,
"filename": "theforecastingcompany-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "6d464ee539c246f79035d1f3478de365",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 113832,
"upload_time": "2025-10-22T16:33:25",
"upload_time_iso_8601": "2025-10-22T16:33:25.508083Z",
"url": "https://files.pythonhosted.org/packages/d9/d3/5afa25e24aea9bb5113181bed55f23675ede43731f3da28d967ab3bd401f/theforecastingcompany-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 16:33:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "theforecastingcompany",
"github_project": "theforecastingcompany-sdk-python",
"github_not_found": true,
"lcname": "theforecastingcompany"
}
JSON
