Unifier API Documentation

Welcome to the Unifier API documentation. This guide will help you understand and use the Unifier API to query time series data with precise bi-temporal controls.

Overview

The Unifier API provides access to harmonized time-series datasets across multiple domains. All data is accessible programmatically through our API or client libraries, with a focus on consistent data models and reliable delivery.

Installation

pip install --upgrade unifier

Authentication

Unifier uses API tokens to authenticate all requests. You can view and manage your tokens through the Unifier user portal.

from unifier import unifier

# Set credentials directly
unifier.user = 'your_username'
unifier.token = 'your_api_token'

Point-in-Time Queries

Unifier's core feature is its ability to support bi-temporal queries across a time series date range. This allows you to retrieve data as it was known at a specific point in time, while also specifying the business time range you're interested in.

Key Concepts

• asof_date: Specifies the point-in-time timestamp. This parameter allows you to query data as it was known on that specific date. If set to None, it will use the most recent asof_date based on your up_to parameter.
• asof_back_to: Defines the start date for querying a range of as-of dates.
• back_to: Defines the start of the business time range (inclusive).
• up_to: Defines the end of the business time range (inclusive).

Bi-temporal Query Model

Unifier's bi-temporal query model allows you to:

• Access historical snapshots of data (as it was known at a specific point in time)
• Query data across a range of as-of dates for different identifiers
• Filter data within specific business date ranges
• Combine time-series data from multiple sources with consistent datetime handling

Parameters

The following parameters can be used when querying the Unifier API:

Parameter	Type	Description	Required
name	string	Name of the dataset or view to query	Yes
asof_date	string (ISO date)	The point-in-time timestamp for querying data. If None, uses most recent asof_date based on up_to	No
asof_back_to	string (ISO date)	Start date for querying a range of as-of dates	No
back_to	string (ISO date)	Start date for the business time range filter (inclusive)	No
up_to	string (ISO date)	End date for the business time range filter (inclusive)	No
key	string	Single key value used to filter the dataset	No
keys	array	List of key values used to filter the dataset	No
limit	integer	Maximum number of records to return	No
disable_view	boolean	If true, disables Unifier's view transformation and returns raw data	No

Unifier Methods

The Unifier Python library provides several methods for interacting with the API:

• get_dataframe(name, **kwargs): Returns query results as a pandas DataFrame.
• get_json(name, **kwargs): Returns query results as a list of JSON objects.
• query(name, **kwargs): Returns the raw response from the API.
• get_asof_dates(name): Returns available as-of dates for a dataset as a pandas DataFrame.

Sample Queries

Basic Query with Business Time Range

This example queries data for Apple (AAPL) within a specific date range:

df = unifier.get_dataframe(
    name="xtech_apollo_group_aggregates_green_buffalo",
    back_to="2025-04-12",
    up_to="2025-04-18",
    key="AAPL",
    asof_date=None  # Uses the latest available data
)

Example output:

Query with As-of Date Range

This example queries data across a range of as-of dates for a specific identifier:

df = unifier.get_dataframe(
    name="lseg_us_reuters_polls",
    key="US&CPIM.Q",
    back_to="2025-01-01",
    up_to="2025-04-30",
    asof_back_to="2025-01-01",
    asof_date="2025-05-12"
)
df = df.sort_values('last_revision_date')
df

Example output:

Point-in-Time Query

This example retrieves data as it was known on April 25, 2025:

df = unifier.get_dataframe(
    name="xtech_apollo_group_aggregates_green_buffalo",
    asof_date="2025-04-25"  # Point-in-time date
)

Example output:

Combined Point-in-Time and Business Time Range

This example combines both bi-temporal filters:

df = unifier.get_dataframe(
    name="xtech_us_equity_options_flow_1min",
    back_to="2025-04-22",    # Business time range start
    up_to="2025-04-29",      # Business time range end
    asof_date="2025-04-30"   # Point-in-time date
)

Multiple Keys with Time Range

This example queries data for multiple securities:

df = unifier.get_dataframe(
    name="xtech_apollo_group_aggregates_green_buffalo",
    back_to="2025-04-01",
    up_to="2025-04-15",
    keys=["AAPL", "MSFT", "GOOGL"],
    asof_date="2025-04-20"
)

Errors

The Unifier API uses HTTP response codes to indicate the success or failure of requests:

Code	Message	Description
200	OK	The request was successful.
400	Bad Request	The request was invalid or improperly formatted.
401	Unauthorized	Authentication failed or credentials were missing.
403	Forbidden	The provided credentials don't have access to the requested resource.
404	Not Found	The requested resource or dataset was not found.
422	Unprocessable Entity	The request was well-formed but contained invalid parameters.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	An unexpected error occurred on the server.
503	Service Unavailable	The service is temporarily unavailable.

Error Handling

It's recommended to implement proper error handling in your code:

try:
    df = unifier.get_dataframe(
        name="xtech_apollo_group_aggregates_green_buffalo",
        back_to="2025-04-12",
        up_to="2025-04-18",
        key="AAPL"
    )
except Exception as e:
    print(f"Error querying data: {e}")
    # Handle the error appropriately