An easy-to-use Python wrapper for the Furnilytics API (organized as topic / subtopic / dataset). Base URL is hardcoded to https://furnilytics-api.fly.dev. For more information about the API, please check out our services page.

Install

From PyPI (recommended, once live):

pip install furnilytics

From source (zip / repo checkout):

pip install -e .
Requires: Python ≥ 3.9 and pandas.

Authenticate

Set your API key once per shell session:

macOS / Linux

export FURNILYTICS_API_KEY="YOUR_KEY"

Windows (PowerShell)

$env:FURNILYTICS_API_KEY="YOUR_KEY"

You don't have an API key yet? Email support@furnilytics.com

1-minute quick start

from furnilytics import Client

cli = Client()  # base URL is preconfigured

# Browse the catalog
topics_df = cli.list_topics()            # one row per subtopic entry (with dataset_count)
flat_df   = cli.list_datasets_flat()     # all datasets with topic/subtopic/name
print(topics_df.head())
print(flat_df.head())

# Inspect a dataset's schema & metadata
meta_df, cols_df = cli.dataset_info("macro_economics","ppi","woodbased_panels_ppi")
print(meta_df)   # shows last_update, time_column, titles/descriptions
print(cols_df)   # columns: name + type

# Query rows as a pandas DataFrame
df = cli.get("macro_economics","ppi","woodbased_panels_ppi", limit=5, country="Italy")
print(df)

Common queries

Filter by columns (two equivalent styles)

# 1) Keyword filters (recommended)
cli.get("macro_economics","ppi","woodbased_panels_ppi", country="Italy", limit=100)

# 2) filters={} dict (sent as JSON behind the scenes)
cli.get("macro_economics","ppi","woodbased_panels_ppi", filters={"country": "Italy"}, limit=100)

Select columns, order, and date window

cli.get(
    "macro_economics","ppi","woodbased_panels_ppi",
    select=["date", "ppi", "country"],
    order_by="date", order_dir="DESC",
    frm="2023-01-01", to="2024-12-31",   # used only if the dataset has a time_column
    country="Italy",
    limit=200
)

Paginate manually

page1 = cli.get("macro_economics","ppi","woodbased_panels_ppi", limit=500, offset=0)
page2 = cli.get("macro_economics","ppi","woodbased_panels_ppi", limit=500, offset=500)

Save to CSV

df = cli.get("macro_economics","ppi","woodbased_panels_ppi", limit=1000)
df.to_csv("woodbased_panels_ppi.csv", index=False)

Minimal API reference

All methods return pandas DataFrame(s).

from furnilytics import Client
cli = Client()  # reads FURNILYTICS_API_KEY; base URL is fixed

Discovery

  • list_topics() -> DataFrame
    One row per subtopic with fields: topic, topic_title, subtopic, dataset_count, etc.
  • list_subtopics(topic: str) -> DataFrame
  • list_datasets(topic: str, subtopic: str) -> DataFrame
  • list_datasets_flat() -> DataFrame
    Flat list of all datasets (includes topic, subtopic, name, title, description, time_column, last_update).

Schema & metadata

  • dataset_info(topic, subtopic, name) -> (meta_df, columns_df)
    meta_df     (single row) and columns_df (name, type).

Data

  • get(topic, subtopic, name, *, filters=None, select=None, order_by=None, order_dir=None, limit=100, offset=0, frm=None, to=None, **column_filters) -> DataFrame

Notes

  • filters may be combined with column_filters (kwargs).
  • frm/to only apply when the dataset defines a time_column.
  • Results are unsorted unless you pass order_by/order_dir.

Command-line (optional)

After install you can also query via a CLI:

# env var for key
export FURNILYTICS_API_KEY="YOUR_KEY"

furnilytics topics
furnilytics subtopics prices
furnilytics datasets prices panels
furnilytics list
furnilytics info prices panels woodbased_panels_ppi
furnilytics get prices panels woodbased_panels_ppi --limit 5 --kv country=SE --csv out.csv

Troubleshooting

  • 401 Invalid or missing API key
    Ensure FURNILYTICS_API_KEY is set in the same shell where you run Python/CLI.
  • 404 Not found
    Double-check topic, subtopic, and name (use list_datasets_flat() to confirm).
  • Empty DataFrame
    Try removing filters, or check spelling/casing of column names passed to select/filters.
  • Ordering fails
    Make sure order_by matches an existing column (see columns_df from dataset_info).

Contact

Questions or dataset requests? Email support@furnilytics.com or open an issue on our repo.