Nominal API Python Client

0.1198.0 · active · verified Fri Apr 17

The official Python client for the Nominal API, providing programmatic access to financial time-series data, including inflation, economic indicators, and asset prices. The library is actively maintained and frequently updated, often releasing new versions with minor bug fixes and feature enhancements, though breaking changes can occur in pre-1.0 releases.

Common errors

```
ImportError: cannot import name 'NominalClient' from 'nominal'
```
cause Attempting to import the old client class name after version 0.1170.0.

fix Change the import to `from nominal import NominalAPIClient`.
```
AttributeError: 'NominalClient' object has no attribute 'get_timeseries'
```
cause You've likely instantiated `NominalClient` (the old class name) which no longer exists or has different methods in newer versions. This can also happen if your code imports an older `NominalClient` then tries to use methods only available on the new `NominalAPIClient`.

fix Ensure you are importing and instantiating `NominalAPIClient`, e.g., `client = NominalAPIClient(...)`.
```
nominal.exceptions.NominalAPIError: Invalid API Key (Status code: 401)
```
cause The provided API key is incorrect, expired, or has insufficient permissions.

fix Double-check your API key for typos. If loading from an environment variable, ensure it's correctly set. Regenerate your key from the Nominal API dashboard if necessary.
```
nominal.exceptions.NominalAPIError: Invalid date format for parameter 'start' (Status code: 400)
```
cause Dates are not provided in the required 'YYYY-MM-DD' string format, especially after version 0.1187.0.

fix Ensure all date parameters are strings formatted as 'YYYY-MM-DD'. If converting from `datetime` objects, use `date_object.strftime('%Y-%m-%d')`.

Warnings

breaking The main client class name changed from `NominalClient` to `NominalAPIClient`.
Fix: Update your import statement from `from nominal import NominalClient` to `from nominal import NominalAPIClient` and all instantiations.
breaking Date parameters for `get_timeseries` and similar methods now require string formats ('YYYY-MM-DD') instead of `datetime` objects.
Fix: Convert any `datetime` objects passed as `start` or `end` parameters to strings using `date_object.strftime('%Y-%m-%d')`.
gotcha The library is still in a pre-1.0 major version (0.x.x), meaning backward-incompatible changes can be introduced in minor or patch releases.
Fix: Always pin your `nominal-api` version in production environments (`nominal-api==X.Y.Z`) and test thoroughly when upgrading to a new version.
gotcha API keys are sensitive. Exposing them in source control or public environments is a security risk.
Fix: Always load your `NOMINAL_API_KEY` from environment variables, a secure vault, or a configuration file that is not committed to source control.

Install

pip install nominal-api Install latest version

Imports

NominalAPIClient
wrong:
```
from nominal import NominalClient
```
correct:
```
from nominal import NominalAPIClient
```
The main client class was renamed from `NominalClient` to `NominalAPIClient` in version 0.1170.0.

Quickstart

Initialize the NominalAPIClient with your API key and fetch time-series data. This example retrieves CPI data for USD for the year 2020. Ensure your API key is configured either as an environment variable or directly in the code.

import os
from nominal import NominalAPIClient

api_key = os.environ.get('NOMINAL_API_KEY', 'YOUR_NOMINAL_API_KEY_HERE')

if api_key == 'YOUR_NOMINAL_API_KEY_HERE':
    print("Please set the NOMINAL_API_KEY environment variable or replace 'YOUR_NOMINAL_API_KEY_HERE' with your actual key.")
else:
    try:
        client = NominalAPIClient(api_key=api_key)
        # Fetch CPI data for USD between specified dates
        timeseries_data = client.get_timeseries("USD.CPI", "2020-01-01", "2020-12-31")
        print("Successfully fetched data:")
        print(f"First entry: {timeseries_data[0]}")
        print(f"Last entry: {timeseries_data[-1]}")
    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →