Welcome to UnacatLib’s documentation!

API Reference

class unacatlib.query_client.QueryClient(api_key: str = '', billing_context: str = '', server_address: str = 'catalog.unacastapis.com', port: int = 443)

Bases: object

A client for querying the Unacast Catalog API.

If no API key is provided, it will attempt to read the API key from the UNACAST_API_KEY environment variable.

Example

>>> from unacatlib import QueryClient
>>> client = QueryClient()  # API key can be provided as an argument or set via UNACAST_API_KEY env variable
>>> response = client.list_records("ml_visitation.foot_traffic_month", limit=100)
>>> df = response.records.to_df()
>>> print(df.head())

get_data_reference(data_reference_name: str) → GetDataReferenceResponse

Get a specific data reference by name.

Parameters:

data_reference_name – The name of the data reference to get

Returns:

GetDataReferenceResponse with data_reference.fields as FieldDefinitionList

list_data_references() → ListDataReferencesResponse

List available data references.

Returns:

ListDataReferencesResponse with data_references as DataReferenceList

list_records(data_reference_name: str, fields: List[str] | None = None, filters: List[FilterClause] | None = None, options: Options | None = None, limit: int | None = None) → PaginatedListRecordsResponse

List records from a data reference with automatic pagination handling.

Parameters:

• data_reference_name – The name of the data reference to query. Use client.list_data_references().data_references.to_df() to get the available data_reference_name.

• fields – Optional list of field names to include in the response. If None, all default fields are returned. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available fields.

• filters – Optional list of filters to apply. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available field and operator to use in the FilterClause. Use the client.search_field_values(data_reference_name, field).values endpoint to get the available values to use in the FilterClause.

• options – Optional query options

• limit – Optional limit on the number of records to return

Returns:

PaginatedListRecordsResponse containing all records and field definitions, inheriting all ListRecordsResponse functionality but without exposing pagination details

Example

>>> from unacatlib import QueryClient, FilterClause
>>> client = QueryClient() # API key can be provided as an argument or set via UNACAST_API_KEY env variable
>>> response = client.list_records(
...     "ml_visitation.foot_traffic_month",
...     fields=["location_id", "brands", "street_address", "observation_start_date", "observation_end_date", "visits_sum"],  # Optional: specify fields to return
...     filters=[
...         FilterClause(
...             field_name="brands",
...             operator="==",
...             value="Target"
...         )
...     ],
...     limit=500
... )
>>> df = response.records.to_df()
>>> print(df.head())

query(data_reference_name: str, fields: List[str] | None = None, filters: List[FilterClause] | None = None, options: Options | None = None, limit: int | None = None) → PaginatedListRecordsResponse

Alias for list_records method. Both methods have identical functionality.

search_field_values(data_reference_name: str, field: str, term: str | None = None, filters: List[FilterClause] | None = None, options: Options | None = None, limit: int | None = None) → PaginatedSearchFieldValuesResponse

Search for distinct values of a field.

Parameters:

• data_reference_name – The name of the data reference to query. Use client.list_data_references().data_references.to_df() to get the available data_reference_name.

• field – The field to search values for. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available field.

• term – Optional search term to filter values

• filters – Optional list of filters to apply. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available field and operator to use in the FilterClause. Use the client.search_field_values(data_reference_name, field).values endpoint to get the available values to use in the FilterClause.

• options – Optional query options

• limit – Optional limit on the number of values to return

Returns:

List of distinct values

Example

>>> from unacatlib import QueryClient
>>> client = QueryClient()  # API key can be provided as an argument or set via UNACAST_API_KEY env variable
>>> response = client.search_field_values("ml_visitation.foot_traffic_month", "brands", "Walm")
>>> print(response)

file_download(data_reference_name: str, fields: List[Field] | None = None, filters: List[FilterClause] | None = None, options: Options | None = None) → FileDownloadResponse

Download a file from a data reference.

Parameters:

• data_reference_name – The name of the data reference to query. Use client.list_data_references().data_references.to_df() to get the available data_reference_name.

• fields – Optional list of field names to include in the download. If None, all default fields are returned. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available fields.

• filters – Optional list of filters to apply. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available field and operator to use in the FilterClause. Use the client.search_field_values(data_reference_name, field).values endpoint to get the available values to use in the FilterClause.

• options – Optional query options

Returns:

FileDownloadResponse containing the download information

Note

This method is currently in alpha and may change.

list_records_statistics(data_reference_name: str, filters: List[FilterClause] | None = None, options: Options | None = None) → ListRecordsStatisticsResponse

Get statistics for records in a data reference.

Parameters:

• data_reference_name – The name of the data reference to query. Use client.list_data_references().data_references.to_df() to get the available data_reference_name.

• filters – Optional list of filters to apply to the records before computing statistics. Use client.get_data_reference(data_reference_name).data_reference.fields.to_df() to get the available field and operator to use in the FilterClause. Use the client.search_field_values(data_reference_name, field).values endpoint to get the available values to use in the FilterClause.

• options – Optional query options

Returns:

ListRecordsStatisticsResponse containing statistical information about the records

Example

>>> client = QueryClient()
>>> stats = client.list_records_statistics("ml_visitation.foot_traffic_month")
>>> print(stats)

Note

This method is currently in alpha and may change.

query_statistics(data_reference_name: str, filters: List[FilterClause] | None = None, options: Options | None = None) → ListRecordsStatisticsResponse

Alias for list_records_statistics method. Both methods have identical functionality.

class unacatlib.query_client.FilterClause(field_name: str = <object object at 0x7f12dd0f5b00>, operator: str = <object object at 0x7f12dd0f5b00>, value: str = <object object at 0x7f12dd0f5b00>, values: List[str] = <object object at 0x7f12dd0f5b00>)

Bases: Message

field_name: str = <object object>

e.g. ‘address_components.<component>.value’

operator: str = <object object>

e.g. ‘==’, ‘!=’, ‘>’, ‘<’, ‘>=’, ‘<=’, ‘in’, ‘not in’

value: str = <object object>

e.g. ‘foo’, ‘bar’, ‘baz’, ‘8’

values: List[str] = <object object>

Only used for ‘in’ or ‘not in’ operator

class unacatlib.query_client.TrimToPeriodOfExistence(value: int)

Bases: Enum

name: str | None

value: int

class unacatlib.query_client.OrderBy(field_name: str = <object object at 0x7f12dd0f5b00>, direction: 'OrderDirection' = <object object at 0x7f12dd0f5b00>)

Bases: Message

direction: OrderDirection = <object object>

Direction

The direction to order by.

Default is ASCENDING.

field_name: str = <object object>

Field name

The field to order by.

class unacatlib.query_client.OrderDirection(value: int)

Bases: Enum

name: str | None

value: int

class unacatlib.query_client.BoundingBox(min_lng: float = <object object>, min_lat: float = <object object>, max_lng: float = <object object>, max_lat: float = <object object>)

Bases: Message

Bounding box

Example: {“minLng”: -74.006, “minLat”: 40.7128, “maxLng”: -73.998, “maxLat”: 40.708}

max_lat: float = <object object>

maxLat

The maximum constant latitude line that bounds the rectangle

max_lng: float = <object object>

maxLng

The eastmost constant longitude line that bounds the rectangle

min_lat: float = <object object>

minLat

The minimum constant latitude line that bounds the rectangle

min_lng: float = <object object>

minLng

The westmost constant longitude line that bounds the rectangle