Snapshot Time Series

Module that handles all Factiva Analytics Time Series requests and objects. Contains classes and tools that allow to run volume volume time series with all possible variations.

SnapshotTimeSeries

class factiva.analytics.snapshots.time_series.SnapshotTimeSeries(job_id=None, user_key=None, query: SnapshotBaseQuery | None = None)

Main class to interact with the Time Series service from Factiva Analytics.

user_key

User representation for service authentication

Type:

UserKey

query

Query object tailored for Extraction operations

Type:

SnapshotExtractionQuery

job_response

Object containing job status and execution details

Type:

SnapshotExtractionJobReponse

Optional = typing.Optional
get_job_response() → bool

Performs a request to the API using the job ID to get its status.

If the job has been completed, results are assigned to the job_response object.

Returns:

True if the get request was successful. An Exception otherwise.

Return type:

bool

process_job()

Submit a new job to be processed, wait until the job is completed and then retrieves the job results.

Returns:

True if the explain processing was successful. An Exception otherwise.

Return type:

bool

submit_job(payload=None)

Performs a POST request to the API using the assigned query to start a TimeSeries job.

If the job is initiated succesfully, results are assigned to the job_response object. Otherwise any HTTP error will raise an exception.

Returns:

True if the submission was successful. An Exception otherwise.

Return type:

bool

SnapshotTimeSeriesQuery

class factiva.analytics.snapshots.time_series.SnapshotTimeSeriesQuery(where=None, includes: dict | None = None, include_lists: dict | None = None, excludes: dict | None = None, exclude_lists: dict | None = None, group_dimension: list[Any] | str | None = None, frequency: str = 'MONTH', date_field: str = 'publication_datetime', top: int = 10)

Snapshot Query for TimeSeries operations class. Used only in the context of SnapshotTimeSeries.

where

User representation for service authentication

Type:

str

includes

Dictionary with a fixed list of codes to include

Type:

dict

includes_list

Dictionary with references to Lists for inclusion

Type:

dict

excludes

Dictionary with a fixed list of codes to exclude

Type:

dict

excludes_list

Dictionary with references to Lists for inclusion

Type:

dict

frequency

Time unit used to aggregate values in the time-series calculation

Type:

str

date_field

Schema date-time field used to calculate the time-series dataset

Type:

str

group_dimension

Field name to break-down aggregates per time period unit

Type:

str

top

Max entries per group_dimension per time period unit

Type:

str

property date_field: str

Get the date_field value.

property frequency: str

Get the frequency value.

get_payload() → dict

Create the basic request payload to be used within Snapshots Explain API request.

Returns:

Dictionary containing non-null query attributes.

Return type:

dict

property group_dimension: list[Any] | str

Get the group_dimension value.

property top: int | None

Get the top value.

SnapshotTimeSeriesJobReponse

class factiva.analytics.snapshots.time_series.SnapshotTimeSeriesJobReponse(job_id: str | None = None)

Snapshot Explain Job Response class. Essentially contains the volume of estimate documents.

job_id

Explain Job ID with a format like abcd1234-ab12-ab12-ab12-abcdef123456.

Type:

str

Unique URL referring to the job instance

Type:

str

job_state

Latest known job status. Value is self-explanatory.

Type:

str

data

Obtained Time-Series data from job execution

Type:

pandas.DataFrame

errors

Job execution errors returned by the API

Type:

list[dict]

property data: DataFrame | None

Get the data DataFrame.

Get the download link.

property errors: list[dict] | None

Get the errors list.

property job_id: str | None

Get the job ID.

property job_link: str | None

Get the job link.

property job_state: str | None

Get the job state.