palanor

The Python client for Palanor Data: the signals, Custom Indices and refined datasets of the Palanor lattice, with the provenance of every value kept on the result.

• One typed client over the REST API at https://api.palanor.com/v1
• Pages are followed for you; max_rows caps a long read
• Retries with exponential backoff on transient errors (429, 502, 503, 504, database timeouts)
• to_pandas() on every result, with provenance kept in df.attrs
• Python 3.9+, one dependency (httpx); pandas is optional

Install

pip install "https://palanor.com/developers/python/palanor-0.1.0-py3-none-any.whl"
# with DataFrames:
pip install "palanor[pandas] @ https://palanor.com/developers/python/palanor-0.1.0-py3-none-any.whl"

Mint a free key at palanor.com/api-tokens (1,000 requests a month, no card), then:

export PALANOR_API_KEY="plnr_..."

Quickstart

from palanor import Palanor

p = Palanor()  # reads PALANOR_API_KEY; or Palanor(api_key="plnr_...")

# A series over a window: every page joined, oldest first
spread = p.signals.observations("rates.spread_2y10y", start="2020-01-01", end="2024-12-31")
print(len(spread), spread.observations[-1])
print(spread.provenance.attribution)      # the credit line owed when you show it

df = spread.to_pandas()                   # DatetimeIndex, one "value" column
df.attrs["provenance"]["license_class"]   # 'public_domain'

# The latest reading, and where it stands in its own record
cpi = p.signals.get("bls_cpi_college_tuition", history=12)
cpi.latest.value, cpi.latest.date, cpi.context["percentile"]

What you can read

Company datasets cover the S&P 500 and take a ticker ("AAPL") or cik=.

own = p.ownership.get("AAPL", limit=10)
own.to_pandas()                     # the 13F holders, largest first
own["five_percent_holders"]         # read any field like a dict
own.provenance                      # {"holders": {...}, "five_percent_holders": {...}}

events = p.events.list("MSFT", items=["1.05", "5.02"], since="2024-01-01")
events.to_pandas()[["filed_at", "item_code", "category"]]

tgt = p.guidance.list(ticker="TGT", metric="eps_adjusted")

Provenance

The API serves a value only when its source may be redistributed, and it says so on the value.

• Signal.provenance and Series.provenance are a Provenance: source, publisher, license_class, license_name, license_url, attribution and redistributable.
• Result.provenance is the response's block as sent. Rows that carry their own block keep it, and to_pandas() flattens it to provenance.source, provenance.license_class and so on.
• Result.provenance_blocks() lists every distinct block in a response.

Show the attribution line wherever you display the data. Terms: palanor.com/terms.

First-reported values

vintage="first" asks for each observation as first published, before revisions. Those values come from ALFRED (Federal Reserve Bank of St. Louis), which isn't licensed for redistribution today, so the call raises PermissionDeniedError. They are shown in the Palanor Terminal.

Errors, retries and your allowance

Every call counts against the key's monthly allowance. result.rate_limit (and p.last_rate_limit) show the tier, the cap and what's left.

Transient failures are retried up to max_retries times (default 3). The wait doubles from backoff seconds (default 0.5) with jitter, and a Retry-After header is honoured.

p = Palanor(max_retries=5, backoff=1.0, timeout=60)

Development

cd packages/palanor-python
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -m "not live"                       # offline: transport, retries, paging, DataFrames
PALANOR_API_KEY=plnr_... pytest -m live    # the live API, about 30 requests
mypy                                       # strict

MIT licensed (the client code). The data is governed by palanor.com/terms and by the license in each result's provenance block.