# Xpansiv Data SDK and API Usage Guide

## Overview

This guide demonstrates how to use the Xpansiv Data API to authenticate, download data, and generate insights through visualization. The workflow combines curl commands for API interactions with Python scripting for data analysis and visualization.

## 1. Obtaining Tokens

Before accessing the Xpansiv Data API, you need to authenticate and obtain access tokens.

**Authentication Request:**


```bash
curl -u 'username:Password' https://api.data.xpansiv.com/auth/login
```

**Response:**

The command will return two tokens:

- **Bearer Token** - Used for API authorization in subsequent requests
- **Refresh Token** - Used to obtain new bearer tokens when they expire


**Best Practice:** Store the bearer token in an environment variable for secure and easy access throughout your session.


```bash
export NG_TOKEN="your_bearer_token_here"
```

## 2. Downloading Data

Once authenticated, you can query the data lake to identify and download files to your local machine.

### Searching for Files

The following example searches for files in the placeholder group name "Example Contracts_RECs" and retrieves up to 100 results:


```bash
curl \
  -H "Authorization: Bearer $NG_TOKEN" \
  'https://api.data.xpansiv.com/file/search?size=100&query=groupName%Example%20Contracts_RECs' \
  | jq -r '.items[] | "\(.fid),\(.fileName)"' \
  | while IFS=',' read -r file_id file_name; do
      # Creates a unique file name using the file ID to prevent overwriting
      local_file_name="${file_name%.csv}_${file_id}.csv"
      
      echo "Downloading $file_name (ID: $file_id) to $local_file_name..."
      
      curl \
        -H "Authorization: Bearer $NG_TOKEN" \
        "https://api.data.xpansiv.com/file/$file_id/download" \
        > "$local_file_name"
    done
```

**What This Does:**

1. **Queries the API** - Searches for files in the specified group
2. **Parses Results** - Uses `jq` to extract file IDs and names from the JSON response
3. **Downloads Files** - Iterates through each file and downloads it with a unique name based on the file ID
4. **Prevents Overwriting** - Appends the file ID to each filename to ensure uniqueness


**Environment Variable:** The `$NG_TOKEN` variable contains your bearer token for authorization.

## 3. Confirming Files Are Ready

After downloading, verify that the data has been successfully imported to your local machine.


```bash
ls -lh *_*.csv
head -n 5 your_downloaded_file.csv
```

Take a quick glance at the files to ensure they were imported properly and aren't corrupted.

## 4. Drawing Value From Data

### Data Filtering

Use Python scripting to filter and prepare your data for analysis. The following example filters based on specific columns:


```python
# Filter data based on PeriodRel and Symbol columns
fdf = df[(df['PeriodRel'].isin(sel_per)) & (df['Symbol'].isin(sel_cont))].copy()
```

**Key Columns:**

- `PeriodRel` - Period relationship/term for the contract
- `Symbol` - Identifier for the specific asset or contract


You can filter on these columns or others based on your analytical needs. For more information on column terminology specific to Xpansiv Data workflows, please refer to the Data Dictionary section.

### Plotting Price With Dates

A significant benefit of the Xpansiv Data system is the ease of accessing and storing data in time series formats. This makes downstream applications like plotting prices against time much simpler.


```python
# Plot data for each contract symbol
for cont in sel_cont:
    group = fdf[fdf['Symbol'] == cont]
    # Add trace using group['Date'] and group['Mid'] or group['Mid_MA']
    # ... plotting code here
```

**What This Does:**

- Iterates through selected contract symbols
- Filters data for each contract
- Plots price data (such as `Mid` prices or moving averages `Mid_MA`) against dates


**Data Points:**

- `Mid` - Mid-price reflecting the average price for assets
- `Mid_MA` - Moving average of mid-prices
- `Date` - Timestamp for each data point


## 5. Example: Market Insight Visualization

Let's visualize price trends for a specific product and term range.

**Scenario:** Filter on the product "New Jersey Class 1 REC" for terms 2026 to 2030, then plot contract prices over time.


```python
import streamlit as st
import pandas as pd
import plotly.express as px

# Load downloaded data
df = pd.read_csv('your_downloaded_file.csv')

# Filter for specific product and terms
sel_per = [2026, 2027, 2028, 2029, 2030]
sel_cont = ['NJ_Class1_REC']

fdf = df[(df['PeriodRel'].isin(sel_per)) & (df['Symbol'].isin(sel_cont))].copy()

# Create visualization
fig = px.line(fdf, x='Date', y='Mid', color='Symbol', title='Contract Prices Over Time')
st.plotly_chart(fig)
```

**Visualization Tools:**

This example uses Streamlit, but you can achieve similar results with:

- **Seaborn** - Statistical data visualization
- **Plotly** - Interactive plotting library
- **Matplotlib** - Basic plotting capabilities


![Graph showing the capabilities of the SDK and API](/assets/pdfshot.07e2f9ddf1a427b3c7d622ed1c4f54f79632f5e0bffde48fc4294b7a7da1b4de.8bd82b2d.png)

Visualizing price of assets over time using API

## Key Benefits

**Speed and Scalability:**
A combination of basic curl commands and simple scripting provides:

- Fast access to market insights
- Scalability to accommodate future data inputs
- Reproducible workflows for ongoing analysis


**Time Series Advantages:**

- Native time series format simplifies temporal analysis
- Easy plotting of prices against time
- Support for trend analysis and forecasting


## API Reference Summary

### Authentication Endpoint


```
POST https://api.data.xpansiv.com/auth/login
```

### File Search Endpoint


```
GET https://api.data.xpansiv.com/file/search?size=<size>&query=<query>
```

### File Download Endpoint


```
GET https://api.data.xpansiv.com/file/<file_id>/download
```

## Best Practices

1. **Token Security** - Always store bearer tokens in environment variables
2. **File Naming** - Use unique identifiers (like file IDs) to prevent overwriting
3. **Data Validation** - Verify downloaded files before processing
4. **Error Handling** - Implement proper error handling in production scripts
5. **Documentation** - Refer to the Data Dictionary for column definitions and terminology


## Next Steps

- Explore additional filtering options based on your data columns
- Implement automated data refresh workflows
- Build dashboards for real-time market monitoring
- Integrate with other data sources for comprehensive analysis