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)[source]¶ 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)[source]¶ 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)[source]¶ 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 resultingCompany
objectReturns: Single Company
object if any company matches the idRaises: DataMonsterError
if no company matches id
-
get_company_by_ticker
(ticker)[source]¶ 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)[source]¶ 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 oncompany_id
.Returns: (dict) details (metadata) for this company, providing basic information.
-
get_data
(datasource, company, aggregation=None, start_date=None, end_date=None)[source]¶ 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 - datasource –
-
get_data_group_by_id
(id)[source]¶ 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 byget_data_groups()
, then call.id
on theDataGroup
object.Parameters: id – (int) Returns: Single DataGroup
object with the given idRaises: DataMonsterError
if no data group matches the given id
-
get_data_group_details
(id)[source]¶ Given a data group id, return the corresponding
DataGroup
objectParameters: id – (int) Returns: Single DataGroup
object with the given idRaises: DataMonsterError
if no data group matches the given id
-
get_data_groups
(query=None)[source]¶ 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)[source]¶ 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.
- datasource –
-
get_datasource_by_id
(datasource_id)[source]¶ 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 resultingDatasource
object.Parameters: datasource_id – (str) Returns: Single Datasource
object with the given idRaises: DataMonsterError
if no data source matches the given id
-
get_datasource_by_name
(name)[source]¶ Given a name, try to find a data source of that name
Parameters: name – (str) Returns: Single Datasource
object with the given nameRaises: DataMonsterError
if no data source matches the given name
-
get_datasource_details
(datasource_id)[source]¶ 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 ondatasource_id
Returns: (dict) details (metadata) for this data source, providing basic information.
-
get_datasources
(query=None, company=None)[source]¶ 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)[source]¶ - Get dimensions (“splits”) for the data source
- from the DataMonster REST endpoint
/datasource/<uuid>/dimensions?filters=...
where thefilters
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
, onlysection_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 onDimensionSet
objects.Raises: DataMonsterError
iffilters
is not a dict or is not JSON-serializable. Re-raisesDataMonsterError
ifself.client.get()
raises that.
Objects¶
-
class
datamonster_api.
Company
(_id, ticker, name, uri, dm)[source]¶ 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
()[source]¶ 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)[source]¶ 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)[source]¶ 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
- company –
-
get_details
()[source]¶ 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)[source]¶ - 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 ofCompany
objects, orNone
. If notNone
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
, onlysection_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)[source]¶ An iterable through a collection of dimensions dictionaries.
Each dimension dictionary has 4 keys:
max_date
,min_date
,row_count
, andsplit_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 insplit_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
-