> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexalis.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Examples

# Python Examples

Learn how to query Nexalis Cloud's real-time API using Python to fetch time-series data and integrate it into your data pipelines.

***

## Basic Query - Fetch scaled data into a JSON

```python theme={null}
import requests

# Configuration
ENDPOINT = "https://yourcompany.app.nexalis.io/api/v0/exec"
READ_TOKEN = "YOUR_READ_TOKEN"

# API query
query = f"""
{{
  'token' '{READ_TOKEN}'
  'class' 'nx.value'
  'labels' {{ 'siteName' 'TX01' 'assetType' 'INV' 'dataObject' 'TotW' }}
  'start' '2026-01-15T00:00:00Z'
  'end' '2026-01-15T01:00:00Z'
}} FETCH
@nexalis/scale
"""

# Execute query
response = requests.post(
    ENDPOINT,
    headers={'Content-Type': 'text/plain; charset=UTF-8'},
    data=query
)

# Get JSON response
data = response.json()
print(data)
```

> ⚠️ **Warning:** This will print all the data directly in your terminal.

The response is a JSON array containing GTS (Geo Time Series) objects with labels, attributes, and time-value pairs.

> 💡 **Tip:** Learn how to use filters and regular expressions in the `labels` parameter to target specific data points. See [Filtering Data](./real-time-api#filtering-data) for examples.

***

## Basic Query - Fetch trapezoidal averages

```python theme={null}
import requests

# Configuration
ENDPOINT = "https://yourcompany.app.nexalis.io/api/v0/exec"
READ_TOKEN = "YOUR_READ_TOKEN"

# API query using the trapezoidal averages macro
query = f"""
{{
  'token' '{READ_TOKEN}'
  'labels' {{ 'siteName' 'TX01' 'assetType' 'INV' 'dataObject' 'TotW' }}
  'start' '2026-01-15T00:00:00Z'
  'end' '2026-01-15T04:00:00Z'
  'bucket_size' 15
}} @nexalis/fetch_trapezoidal_averages
"""

# Execute query
response = requests.post(
    ENDPOINT,
    headers={'Content-Type': 'text/plain; charset=UTF-8'},
    data=query
)

# Get JSON response
data = response.json()
print(data)
```

This macro automatically fetches the data, scales it, and computes trapezoidal averages for the specified time range, returning averaged values (here 15-min averages) instead of raw data points.

> 💡 **Tip:** Learn how to use filters and regular expressions in the `labels` parameter to target specific data points. See [Filtering Data](./real-time-api#filtering-data) for examples.

***

## Convert JSON response to Pandas DataFrame

Once you have the JSON response, you can parse it and convert it to a pandas DataFrame:

```python theme={null}
import pandas as pd

# We assume here that you already have the http response
# response = requests.post( ... )
data = response.json()

gts_list = response.json()[0]

# Convert to DataFrame
rows = []

# Loop through the list of GTS
for gts in gts_list:
    labels = gts.get("l", {})
    attributes = gts.get("a", {})

    # Loop through the values/timestamps for each GTS
    for ts_us, *_, val in gts.get("v", []):
        rows.append((
        labels.get("siteName",""),
        labels.get("deviceModel",""),
        labels.get("deviceID",""),
        labels.get("dataPoint",""),
        attributes.get("description",""),
        ts_us,
        val,
        attributes.get("engUnits",""),
        attributes.get("subDeviceID",""),
        attributes.get("assetType",""),
        attributes.get("logicalNode",""),
        attributes.get("dataObject",""),
        attributes.get("subDataObject",""),
        attributes.get("measurementType",""),
        attributes.get("multiplier",""),
        attributes.get("adder",""),
        attributes.get("protocol","")
        ))

# Create a dataframe and set specify its columns
df = pd.DataFrame(rows, columns=[
"siteName","deviceModel","deviceID","dataPoint","description",
"timestamp","value","engUnits","subDeviceID","assetType",
"logicalNode","dataObject","subDataObject","measurementType",
"multiplier","adder","protocol"
])

# Convert unix microseconds time to date/time
df["timestamp"] = pd.to_datetime(df["timestamp"], unit="us", utc=True)

print(df.head())
```

> ⚠️ **Warning:** Even if we're only displaying a few rows of the dataframe (df.head()), your machine is loading it all to memory (pd.DataFrame(rows, columns\[...])). It won't be a problem for small dataframes but it can be slow for larger ones.

This approach parses the GTS format into a flat DataFrame structure, making it easy to analyze with pandas or save to Delta Lake for further processing.

## Create Plot: Values = f(Time)

Here is a short snippet to create a plot with matplotlib. Here we're plotting values as a function of time, grouping by "subDeviceID".

```python theme={null}
import matplotlib.pyplot as plt

# We assume here that you already have a pandas DataFrame 'df'
# with at least the columns 'value', 'timestamp', 'subDeviceID'

plt.figure(figsize=(12, 6))
 
fig, ax = plt.subplots(figsize=(12, 6))
 
g = df.sort_values("timestamp").groupby("subDeviceID")
 
g.plot(x="timestamp", y="value", ax=ax, legend=False)
 
ax.legend(ax.get_lines(), g.groups.keys(), title="Legend")
 
ax.set_title("Value over time by subDeviceID")
ax.set_xlabel("Timestamp (UTC)")
ax.set_ylabel("Value")
ax.grid(True)
plt.show()
```

## Save as Delta table

```python theme={null}
from deltalake import write_deltalake, DeltaTable

# We assume here that you already have a pandas DataFrame 'df'

print(df.head())

write_deltalake('./tmp/nexalis_data', df, mode='append')
print("Data saved to Delta table!")
```

***

## Next Steps

* Learn about [Nexalis Macros](./nexalis-macros) for simplified queries
* Explore [PowerBI integration](./powerbi-examples) for dashboards
* Review the [API documentation](./real-time-api) for more details