Furnilytics Python Library

A lightweight, production-ready Python wrapper for the Furnilytics REST API.

The client abstracts HTTP handling, authentication, rate-limiting, and error management, returning datasets as Pandas DataFrames for immediate analytical use.

Supports:

• /datasets catalog discovery
• /metadata inspection
• /data/{id} retrieval
• Public and API-key protected datasets

Ideal for research automation, dashboards, and quantitative analysis pipelines.

Links

• API docs: https://www.furnilytics.com/platform/api/#api-python
• Data catalogue: https://www.furnilytics.com/platform/data-catalogue/
• API discovery: https://api.furnilytics.com/
• OpenAPI schema: https://api.furnilytics.com/openapi.json
• GitHub source: https://github.com/Furnilytics/Furnilytics_lib
• PyPI package: https://pypi.org/project/furnilytics/

Installation

pip install furnilytics

Authentication

Public datasets can be accessed without an API key.

Pro datasets require an API key via the X-API-Key header.

Option 1 — Environment Variable (recommended)

export FURNILYTICS_API_KEY="your_api_key"

On Windows PowerShell:

$env:FURNILYTICS_API_KEY="your_api_key"

Option 2 — Pass directly to Client

from furnilytics import Client

cli = Client(api_key="your_api_key")

Quick Start

from furnilytics import Client

cli = Client()

# API health
print(cli.health())

# List available datasets
datasets = cli.datasets()
print(datasets.head())

# List metadata
meta = cli.metadata()
print(meta.head())

# Get metadata for one dataset
info = cli.metadata_one("other/materials/eu_pb_price")
print(info["meta"])

# Fetch dataset rows
df = cli.data("other/materials/eu_pb_price", limit=10, geo=["PL", "DE"])
print(df.head())

Core Endpoints Covered

The client wraps the following API endpoints:

Dataset IDs use the format:

topic/subtopic/table_id

Example:

macro_economics/prices/eu_hicp_energy

Filtering Data

The data() method supports optional filters:

df = cli.data(
    "other/materials/eu_pb_price",
    frm="2020-01-01",
    to="2023-12-31",
    limit=1000
)

Parameters:

• frm — start date (YYYY-MM-DD)
• to — end date (YYYY-MM-DD)
• limit — max rows (server limit applies)
• <column>=value — filter by any column (e.g. geo=PL)

Public vs Pro Datasets

Datasets include a visibility field:

• "public" — accessible without API key
• "paid" / "pro" — requires API key

If a Pro dataset is accessed without a key, the client raises:

AuthError

Example:

from furnilytics import Client, AuthError

cli = Client(api_key=None)

try:
    cli.data("some/pro/dataset")
except AuthError as e:
    print("Access denied:", e)

Error Handling

The client raises structured exceptions:

Example:

try:
    df = cli.data("unknown/id")
except NotFoundError:
    print("Dataset does not exist.")

Debugging

You can inspect response metadata:

cli.data("macro_economics/prices/eu_hicp_energy", limit=5)
print(cli.last_response_meta)

Includes:

• HTTP status
• ETag
• Cache headers
• Rate-limit headers (if present)

Development

Clone the repository:

git clone https://github.com/Furnilytics/Furnilytics_lib.git
cd Furnilytics_lib
pip install -e .

Build locally:

python -m build

Publish to PyPI via tagged release:

git tag v0.2.x
git push origin v0.2.x

Project Structure

furnilytics/
 ├── client.py
 ├── __main__.py
 └── __init__.py

Requirements

• Python 3.9+
• requests
• pandas

About Furnilytics

Furnilytics is a data-driven market intelligence initiative focused on the global furniture industry, integrating macroeconomic, trade, retail, and digital demand data into structured datasets and analytical indicators.

Website: https://www.furnilytics.com

API documentation: https://www.furnilytics.com/platform/api/#api-python

Dataset catalogue: https://www.furnilytics.com/platform/data-catalogue/

License & scope

MIT License

This license applies only to the Python client library code.

Access to and usage of the Furnilytics API and its datasets are governed by separate Terms of Service.