news.taxonomy

Taxonomy

class factiva.news.taxonomy.Taxonomy(user_key=None)

Bases: object

Class that represents the taxonomy available within the Snapshots API.

Parameters

user_key (str or UserKey) – String containing the 32-character long APi Key. If not provided, the constructor will try to obtain its value from the FACTIVA_USERKEY environment variable.

Examples

Creating a taxonomy instance providing the user key
>>> t = Taxonomy(u='abcd1234abcd1234abcd1234abcd1234')
Creating a taxonomy instance with an existing UserKey instance
>>> u = UserKey('abcd1234abcd1234abcd1234abcd1234')
>>> t = Taxonomy(user_key=u)
categories = []
get_categories() → list

Request for a list of available taxonomy categories.

Return type

List of available taxonomy categories.

Raises

RuntimeError – When API request returns unexpected error:

Examples

This method is called with in the __init__ method, so the categories can be accessed as is.
>>> taxonomy = Taxonomy()
>>> print(taxonomy.categories)
['news_subjects', 'regions', 'companies', 'industries', 'executives']
Calling the method on its own
>>> taxonomy = Taxonomy()
>>> print(taxonomy.get_categories())
['news_subjects', 'regions', 'companies', 'industries', 'executives']
get_category_codes(category) → DataFrame

Request for available codes in the taxonomy for the specified category.

Parameters

category (str) – String with the name of the taxonomy category to request the codes from

Return type

Dataframe containing the codes for the specified category

Raises

  • ValueError – When category is not of a valid type:

  • RuntimeError – When API request returns unexpected error:

Examples

Getting the codes for the ‘industries’ category
>>> taxonomy = Taxonomy()
>>> industry_codes = taxonomy.get_category_codes('industries')
>>> print(industry_codes)
        code                description
0     i25121             Petrochemicals
1     i14001         Petroleum Refining
2       i257            Pharmaceuticals
3     iphrws  Pharmaceuticals Wholesale
4       i643     Pharmacies/Drug Stores
get_company(code_type, company_codes) → DataFrame

Request information about either a single company or a list of companies.

Parameters

  • code_type (str) – String describing the code type used to request the information about the company. E.g. isin, ticker.

  • company_code (str or list) – Single company code (str) or list of company codes to translate.

Return type

Dataframe with the information about the requested company(ies)

Raises

  • ValueError – When any given argument is not of the expected type:

  • RuntimeError: –

    • When both company and companies arguments are set - When API request returns unexpected error

Examples

Get data for a single company using the code type ‘isin’
>>> taxonomy = Taxonomy()
>>> single_company_data = taxonomy.get_company('isin', company_code='ABCNMST00394')
>>> print(single_company_data)
             id  fcode           common_name
0  ABCNMST00394  ABCYT  Systemy Company S.A.
Get data for multiple companies sugin the code type ‘isin’
>>> taxonomy = Taxonomy()
>>> multiple_companies_data = taxonomy.get_company('isin', company_codes=['ABC3E53433100', 'XYZ233341067', 'MN943181045'])
>>> print(multiple_companies_data)
             id   fcode      common_name
0  ABC3E5343310  MCABST  M**************
1  XYZ233341067   AXYZC    A************
2  MN9431810453     MNM     M***********
get_identifiers() → list

Request for a list of available taxonomy categories.

Return type

List of available taxonomy categories.

Raises

RuntimeError – When API request returns unexpected error:

Examples

This method is called with in the __init__ method, so the categories can be accessed as is.
>>> taxonomy = Taxonomy()
>>> print(taxonomy.categories)
['news_subjects', 'regions', 'companies', 'industries', 'executives']
Calling the method on its own
>>> taxonomy = Taxonomy()
>>> print(taxonomy.get_categories())
['news_subjects', 'regions', 'companies', 'industries', 'executives']
get_multiple_companies(code_type, company_codes) → DataFrame

Request information about a list of companies.

Parameters

  • code_type (str) – String describing the code type used to request the information about the company. E.g. isin, ticker.

  • companies_codes (list) – List containing the company codes to request information about

Return type

DataFrame containing the company information

Raises

RuntimeError – When API request returns unexpected error:

Examples

Get multiple companies data using the code type ‘isin’ and a company codes list
>>> taxonomy = Taxonomy()
>>> companies_data = taxonomy.get_multiple_companies('isin', ['ABC3E53433100', 'XYZ233341067', 'MN943181045'])
>>> print(companies_data)
             id   fcode      common_name
0  ABC3E5343310  MCABST  M**************
1  XYZ233341067   AXYZC    A************
2  MN9431810453     MNM     M***********
get_single_company(code_type, company_code) → DataFrame

Request information about a single company.

Parameters

  • code_type (str) – String describing the code type used to request the information about the company. E.g. isin, ticker.

  • company_code (str) – String containing the company code

Return type

DataFrame containing the company information

Raises

RuntimeError – When API request returns unexpected error:

Examples

Get the company data using the code type ‘isin’ and the company code ‘ABCNMST00394’
>>> taxonomy = Taxonomy()
>>> company_data = taxonomy.get_single_company('isin', 'ABCNMST00394')
>>> print(company_data)
             id  fcode           common_name
0  ABCNMST00394  ABCYT  Systemy Company S.A.
identifiers = []

Company

class factiva.news.taxonomy.Company(user_key=None)

Bases: object

Class that represents the company available within the Snapshots API.

Parameters

user_key (str or UserKey) – String containing the 32-character long APi Key. If not provided, the constructor will try to obtain its value from the FACTIVA_USERKEY environment variable.

Examples

Creating a company instance providing the user key
>>> c = Company(u='abcd1234abcd1234abcd1234abcd1234')
Creating a company instance with an existing UserKey instance
>>> u = UserKey('abcd1234abcd1234abcd1234abcd1234', True)
>>> c = Company(user_key=u)
point_in_time_download_all(identifier, file_name, file_format, to_save_path=None, add_timestamp=False) → str

Returns a file with the historical and current identifiers for each category and news coded companies.

Parameters

  • identifier (str) – A company identifier type

  • file_name (str) – Name to be used as local filename

  • file_format (str) – Format of the file

  • to_save_path (str, optional) – Path to be used to store the file

  • add_timestamp (bool, optional) – Flag to determine if include timestamp info at the filename

Returns

Dowloaded file path

Return type

str

Raises

  • ValueError – When the user is not allowed to permorm this operation:

  • ValueError – When the identifier requested is not valid:

  • ValueError – When the format file requested is not valid:

point_in_time_query(identifier, value) → dict

Returns the resolved Factiva code and date ranges when the instrument from the identifier, was valid.

Parameters

  • identifier (str) – A company identifier type

  • value (str) – Identifier value

Returns

Factiva code and date ranges from a company

Return type

dict

Raises

  • ValueError – When the user is not allowed to permorm this operation:

  • ValueError – When the identifier requested is not valid:

user_key = None
validate_point_time_request(identifier)

Validate if the user is allowes to perform company operation and if the identifier given is valid

Parameters

identifier (str) – A company identifier type

Raises

  • ValueError – When the user is not allowed to permorm this operation:

  • ValueError – When the identifier requested is not valid: