ams-sdk 1.0.9

Python SDK for the Alternative Macro Signals API

AMS-SDK

ams-sdk is a wrapper around ams-api and handles the authentification and query process in just a few steps.

Please refer to AMS API documentation for a detailed description of the API endpoints, including parameters specification.

---

Features ✨

• Easy Queries: Query from all AMS API endpoints in two lines of Python code

• Authentication: SDK takes care of the full authentication process, with just your API key required (given by AMS)

---

Installation 🛠️

From PyPI (recommended):

pip install ams-sdk

Alternatively, directly from repo:

pip install git+https://github.com/alternative-macro-signals/ams-sdk.git

---

Requirements 📋

The following dependencies are necessary to use this SDK:

• Python 3.7 or higher (likely to work with 3+ but not tested)
• requests>=2.0.0 (installed automatically if needed)

---

Usage 📖

Initialization

First, initialize the AMSClient with the service URL and API key provided by AMS.

from ams_sdk.client import AMSClient

client = AMSClient(service_url=SERVICE_URL, api_key=API_KEY)

Authentication

Call the authenticate() method to fetch the bearer token required for further requests:

client.authenticate()

Querying Endpoints

Use the query_endpoint method to query specific AMS API endpoints:

result = client.query_endpoint("/nbstat", params={
 "location": "Japan",
 "txt": "rice",
 "start": "2023-01-01",
 "end": "2025-06-01"
})
print(result)

For /nbstat, location, sector and sign also accept lists — the result is one combined aggregate series over all the values (Neutral is accepted as an alias for Undefined):

result = client.query_endpoint("/nbstat", params={
 "location": ["US", "UK"],
 "sector": ["Core", "Energy"],
})
print(result)

result = client.query_endpoint("/nipi", params={
 "location": "China",
 "sector": "Food",
})
print(result)

# Query Entropy data (returns all 3 signs: p_neg, p_pos, p_neu)
result = client.query_endpoint("/nipi", params={
 "metric": "Entropy",
 "location": "US",
 "sector": "All",
 "start": "2024-01-01"
})

# Query single entropy sign
result = client.query_endpoint("/nipi", params={
 "metric": "Entropy",
 "location": "US",
 "sign": "p_pos"  # p_neg, p_pos, or p_neu
})

Note: see /nbstat and /nipi endpoints documentations for accepted parameters details.

Output

Transform the /nbstat or /nipi output in a Pandas dataframe:

import pandas as pd
df = pd.DataFrame(result.get('content'))
df['date'] = pd.to_datetime(df['date'])
df = df.set_index('date')
df.sort_index(inplace=True)

In order to get 7-day and 30-day rolling balances from /nbstat (similar to the NewsBot app):

df7 = df.rolling(7).mean()
df30 = df.rolling(30).mean()

Note: NIPI is already a 30-day rolling diffusion index.

Entropy output: When querying with metric=Entropy, the response contains 3 rows per date (one for each sign: p_neg, p_pos, p_neu) unless filtered with the sign parameter. The meta.metric_2 field identifies which sign each row represents.

---

API endpoints callable from AMSClient 🌐

/nbstat

Retrieve Inflation News Balance and News Volumes associated with specific text queries.

/nipi

Download NIPI, NVI, or Entropy data. Use the metric parameter to select:

• NIPI (default): News Inflation Pressure Index (30-day rolling diffusion index)
• NVI: News Volume Index
• Entropy: Raw entropy values (building blocks of NIPI). Use sign parameter to filter: p_neg, p_pos, p_neu

/newsbot

Beta — shape may change; not yet in the formal API reference.

The daily Inflation/Wages NewsBot feed (the curated daily news list) as JSON, latest or by date. Requires a key entitled for this feed (api_newsbot for inflation, api_newsbot_wages for wages).

Parameters:

Param	Values	Notes
topic	inflation (default), wages
tz	et (London AM), ny (NY PM)	wages: et only
date	YYYY-MM-DD	omit for the latest edition
index	1	list available publications (metadata only)

# latest London-AM inflation newsbot
result = client.query_endpoint("/newsbot", params={"topic": "inflation", "tz": "et"})

# what's available
client.query_endpoint("/newsbot", params={"topic": "inflation", "index": 1})

The response content.payload is the daily news list (a releaseTime plus numbered items). Each item carries region, loc, stars, title, srce, publishedAt, url, sum, lang, sector and a themes list of category labels (beta — exposed via the API only).

---

We welcome suggestions! 💡

📧: [e-mail]

---

Project Structure 📂

• client.py: Contains the AMSClient class which offers the core functionality for interacting with the API.
• utils.py: AMSClient usage examples.
• setup.py: Handles package configuration and installation details.
• README.md: Documentation for the ams-sdk.

---

License 📜

This project is licensed under the MIT License. See the LICENSE file for details.

---

Author

• Author: Laurent Bilke - [e-mail]
• Repository: GitHub

---

© 2025 Alternative Macro Signals. All rights reserved. https://alt.ms