API & Python Access

Quick start

Every dataset in Furnilytics is identified by a unique dataset ID using the format topic/subtopic/table_id. The same ID is used across the data catalogue, Python client, and HTTP API.

Example dataset ID:

other/materials/eu_pb_price

In practice, most users follow a simple workflow: first identify the dataset in the catalogue, then inspect its metadata if needed, and finally retrieve the data rows either through Python or through a direct API request.

Authentication

Public datasets can be accessed without an API key. Pro datasets require an API key, which must be included in the X-API-Key request header.

In Python, the API key can either be passed directly to the client or set through the FURNILYTICS_API_KEY environment variable.

export FURNILYTICS_API_KEY="your_api_key"

On Windows PowerShell:

$env:FURNILYTICS_API_KEY="your_api_key"

Python wrapper

The Furnilytics Python library is the recommended option for Python-based workflows. It wraps the API, handles authentication and common HTTP issues, and returns datasets directly as Pandas DataFrames.

Install

pip install furnilytics

Basic example

from furnilytics import Client

cli = Client()

# API health
print(cli.health())

# List available datasets
datasets = cli.datasets()
print(datasets.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())

This makes the Python client well suited for notebooks, automated reporting, ETL jobs, analytical backends, and dashboard pipelines.

Core methods

• health() — check API status
• datasets() — list available datasets
• metadata() — inspect metadata for all datasets
• metadata_one(id) — inspect one dataset
• data(id) — retrieve dataset rows

HTTP API

Furnilytics datasets can also be accessed directly through standard HTTP requests. This is useful for BI tools, web-based connectors, data platforms, and environments where you prefer not to use the Python wrapper.

Base URL & endpoints

The main API endpoints are:

• /health — API status check
• /datasets — dataset catalogue
• /metadata — metadata for all datasets
• /metadata/{table_id} — metadata for one dataset
• /data/{table_id} — dataset rows

Example requests

Example request for data rows:

GET /data/other/materials/eu_pb_price?geo=PL&limit=100

Example with curl and API key:

curl -H "X-API-Key: your_api_key" \
"https://api.furnilytics.com/data/other/materials/eu_pb_price?geo=PL,DE&limit=100"

Example metadata request:

GET /metadata/other/materials/eu_pb_price

Filtering

The /data/ endpoint supports a few standard parameters:

• frm — start date in YYYY-MM-DD format
• to — end date in YYYY-MM-DD format
• limit — maximum number of rows
• <column>=value — filter by dataset column, for example geo=PL

Text filters are case-insensitive and support comma-separated multi-select values. For example, geo=PL,DE returns rows for both Poland and Germany.

GET /data/other/materials/eu_pb_price?geo=PL,DE&frm=2023-01-01&limit=500

Public vs Pro datasets

Furnilytics includes both public and Pro datasets. Public datasets can be requested directly without authentication. Pro datasets require a valid API key.

Dataset metadata includes a visibility field, allowing users to distinguish between public and paid/pro access tiers before integrating the table into a workflow.

For many users, the public datasets are the best place to start. They can be explored on the website, inspected in the catalogue, and integrated directly through the API.

Error handling

The Python client raises structured exceptions for the most common API problems, including authentication errors, missing datasets, and rate limits.

• AuthError — missing or invalid API key
• NotFoundError — dataset not found
• RateLimitError — too many requests
• ClientError — other client or server errors

In raw HTTP usage, these are returned as standard API error responses with the relevant status code.