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(user_key=None, query=None, job_id=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

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()

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, frequency: str = 'MONTH', date_field: str = 'publication_datetime', group_dimensions: list = [], top: int = 10)

Snapshot Query for TimeSeries operations class. Used only in the context of SnapshotTimeSeries, but can be transformed to other SnapshotQuery types when those are created using an instance of this class as parameter.

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_dimensions

List of fields to break-down aggregates per time period unit

Type:

list[str]

top

Max entries per group_dimension per time period unit

Type:

str

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

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

job_link

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]