This part of the documentation covers all the interfaces of the datamonster-api.

Interface

class datamonster_api.DataMonster(key_id, secret, server=None, verify=True)

DataMonster object. Main entry point to the library

Parameters:

• key_id – (str) a user’s public key
• secret – (str) a user’s secret key
• server – (optional, str) default to dm.adaptivemgmt.com
• verify – (optional, bool) whether to verify the server’s TLS certificate

get_companies(query=None, datasource=None)

Get available companies

Parameters:

• query – Optional query that will restrict companies by ticker or name
• datasource – Optional Datasource object that restricts companies to those covered by the given data source

Returns:

Iterator of Company objects

get_company_by_id(company_id)

Get a single company by id

Parameters:company_id – (str or int) unique internal identifier for the desired company. Can take str form e.g. ‘718’, or int form, e.g. 707. In order to find the id of a frequently used company, find the company by ticker and call .pk on the resulting Company object Returns:Single Company object if any company matches the id Raises:DataMonsterError if no company matches id

get_company_by_ticker(ticker)

Get a single company by ticker

Parameters:ticker – Ticker to search for Returns:Single Company object if any companies exactly match the ticker (case insensitive) Raises:DataMonsterError if no companies match ticker

get_company_details(company_id)

Get details for the given company

Parameters:company_id – (str or int) unique internal identifier for company. See the method
get_company_by_id for more info on company_id. Returns:(dict) details (metadata) for this company, providing basic information.

get_data(datasource, company, aggregation=None, start_date=None, end_date=None)

Get data for data source

Parameters:

• datasource – Datasource object to get the data for
• company – Company object to filter the data source on
• aggregation – Optional Aggregation object to specify the aggregation of the data
• start_date – Optional filter for the start date of the data
• end_date – Optional filter for the end date of the data

See here for example usage.

Returns:pandas.DataFrame

get_data_group_by_id(id)

Give a data group pk (primary key), return the corresponding DataGroup object. To find the pk for a data group, first find it using the iterator returned by get_data_groups(), then call .id on the DataGroup object.

Parameters:id – (int) Returns:Single DataGroup object with the given id Raises:DataMonsterError if no data group matches the given id

get_data_group_details(id)

Given a data group id, return the corresponding DataGroup object

Parameters:id – (int) Returns:Single DataGroup object with the given id Raises:DataMonsterError if no data group matches the given id

get_data_groups(query=None)

Get available data groups

Parameters:query – (str) Optional query that will restrict data groups by name or data source name Returns:Iterator of DataGroup objects.

get_data_raw(datasource, filters=None, aggregation=None)

Get raw data for all companies available in the data source.

Parameters:

• datasource – Datasource object to get the data for
• aggregation – Aggregation object to specify requested aggregation
• filters – dictionary of requested filters

Returns:

(schema, pandas.DataFrame)

See here for example usage.

get_datasource_by_id(datasource_id)

Given a data source UUID (universal unique identifier), return the corresponding Datasource object. To find the UUID for a data source, first find it by name, then call .id on the resulting Datasource object.

Parameters:datasource_id – (str) Returns:Single Datasource object with the given id Raises:DataMonsterError if no data source matches the given id

get_datasource_by_name(name)

Given a name, try to find a data source of that name

Parameters:name – (str) Returns:Single Datasource object with the given name Raises:DataMonsterError if no data source matches the given name

get_datasource_details(datasource_id)

Get details (metadata) for the data source corresponding to the given UUID

Parameters:datasource_id – (str) See the method
get_datasource_by_id for more info on datasource_id Returns:(dict) details (metadata) for this data source, providing basic information.

get_datasources(query=None, company=None)

Get available datasources

Parameters:

• query – (str) Optional query that will restrict data sources by name or provider name
• company – Optional Company object that restricts data sources to those that cover the given company

Returns:

Iterator of Datasource objects

get_dimensions_for_datasource(datasource, filters=None, add_company_info_from_pks=False)

Get dimensions (“splits”) for the data source

from the DataMonster REST endpoint /datasource/<uuid>/dimensions?filters=... where the filters string is optional.

Parameters:

• datasource – Datasource object
• filters – (dict): a dict of key/value pairs to filter dimensions by
• add_company_info_from_pks – (bool): Determines whether return value will include tickers for the returned companies. If False, only section_pk s will be returned.

See here for example usage.

Returns:a DimensionSet object - an iterable through a collection of dimension dicts, filtered as requested. See this documentation for more info on DimensionSet objects. Raises:DataMonsterError if filters is not a dict or is not JSON-serializable. Re-raises DataMonsterError if self.client.get() raises that.

get_raw_data(*args, **kwargs)

This function is deprecated. Please use the get_data_raw function instead

Objects

class datamonster_api.Company(_id, ticker, name, uri, dm)

Representation of a company in DataMonster

Parameters:

• _id – (str) unique internal identifier for the company
• ticker – (str) ticker of the company
• name – (str) name of the company
• uri – (str) DataMonster resource identifier associated with the company
• dm – DataMonster object

property ticker

Returns: (str) company ticker, None if company is private

property name

Returns: (str) company name, including the associated vendor

property quarters

Returns: (list) list of company quarter dates, including 4 projected dates.

Empty if company is private

datasources

Returns:(iter) iterable of Datasource objects associated with this company to which the user has access, memoized

get_details()

Get details (metadata) for this company, providing basic information as stored in DataMonster

Returns:(dict)

pk

Returns:(int) the unique internal identifier for the company (corresponds to _id)

class datamonster_api.Datasource(_id, name, category, uri, dm)

Representation of a data source in DataMonster

Parameters:

• _id – (str) unique internal identifier for the data source
• name – (dict) name of the data source, including the vendor for the data
• category – (list) associated categories
• uri – (str) DataMonster resource identifier associated with the data source
• dm – DataMonster object

property name

Returns (str) name of data source, including vendor

property category

Returns (str) category associated with the data source, e.g., Web Scrape Data or Uploaded Data

companies

Returns:(iter) iterable of Company objects associated with this data source, memoized

get_data(company, aggregation=None, start_date=None, end_date=None)

Get data for this data source.

Parameters:

• company – Company object to filter the data source on
• aggregation – Optional Aggregation object to specify the aggregation of the data
• start_date – Optional string to act as a filter for the start date of the data; accepted formats include: YYYY-MM-DD, MM/DD/YYYY, or pandas or regular datetime object
• end_date – Optional string to act as a filter for the end date of the data; accepted formats include: YYYY-MM-DD or MM/DD/YYYY, or pandas or regular datetime object

Returns:

pandas.DataFrame

get_details()

Get details (metadata) for this data source, providing basic information as stored in DataMonster

Returns:(dict)

get_dimensions(company=None, add_company_info_from_pks=True, **kwargs)

Return the dimensions for this data source,

restricted to the given company or companies and filtered by any kwargs items. Not memoized.

Parameters:

• company – a Company object, a list or tuple of Company objects, or None. If not None the return value will only include rows corresponding to the given companies.
• add_company_info_from_pks – Determines whether return value will include tickers for the returned companies. If False, only section_pk s will be returned.
• kwargs – Additional items to filter by, e.g. category='Banana Republic'

Returns:

a DimensionSet object - an iterable through a collection of dimension dicts, filtered as requested. See this documentation for more info.

See here for example usage of a similar function.

Raises:can raise DataMonsterError if company is not of an expected type, or if some kwarg item is not JSON-serializable.

class datamonster_api.DimensionSet(url, dm, add_company_info_from_pks)

An iterable through a collection of dimensions dictionaries.

Each dimension dictionary has 4 keys: max_date, min_date, row_count, and split_combination. The first two have values that are dates as strings in ISO format; split_combination points to a dict containing data from all other columns; row_count points to an int specifying how many rows match the dates and all splits in split_combination

has_extra_company_info

Returns:(bool) The value passed as add_company_info_from_pks to the constructor, coerced to bool.

max_date

Returns:(str) max of the max_date of the dimension dicts

min_date

Return type:(str) min of the min_date of the dimension dicts

row_count

Returns:(int) number of rows matching the filters for this DimensionSet

class datamonster_api.Aggregation(period, company)

A representation of an aggregation type within DataMonster

Data Upload

class datamonster_api.DataGroup(_id, name, columns, status, dm)

Representation of a DataGroup in DataMonster

Parameters:

• _id – (int) unique internal identifier for the Data Group
• name – (str) name of the Data Group
• columns – (list of DataGroupColumn objects) representing columns of uploaded data
• status – (str, enum) Status of the DataSources in DataGroup at instantiation time. This property is updated by get_current_status. It can take one of the following three values. success if all Data Sources in the group have successfully loaded processing if any DataSource in the group is still processing error if any DataSource in the group is in an error state Note: error takes precedence over processing
• dm – DataMonster object

get_current_status()

Query Data Monster servers for the most up-to-date status of this DataGroup. Calling this method will update the status field on this instance and return it.

Returns:The status of this DataGroup. Values can be one of the following: success if all Data Sources in the group have successfully loaded processing if any DataSource in the group is still processing error if any DataSource in the group is in an error state Note: error takes precedence over processing

get_details()

Get details (metadata) for this data group, providing basic information as stored in DataMonster

Returns:(dict)

class datamonster_api.DataGroupColumn(name=None, type_=None)

Representation of a DataGroupColumn in DataMonster

Parameters:

• name – (str) name of the DataGroupColumn
• type – (enum ‘string’, ‘number’ or ‘date’) expected data type of the column