Material Queries

The EC3Materials class is meant to simplify the querying of materials from the EC3 database

The primary method currently setup for this class is the ‘get_materials’ method. When using this the user should pass a dictionary of parameters and values for querying.

There are a large number of fields listed in the EC3 documentation that can be used to query materials. Users should refer to that documentation for the field names and values expected.

A small number of commonly used fields have been built into the class. Refer to documentation below to see further details.

EC3Materials

class ec3.ec3_materials.EC3Materials(bearer_token, response_format='json', ssl_verify=True)

Wraps functionality of EC3 Materials

Variables

  • return_fields (list) – List of the fields you would like returned (EC3 returns everything by default), defaults to []

  • sort_by (str) – Optional name of return field to sort results by, defaults to “”

  • only_valid (bool) – If True will return only Materials with EPDs that are currently valid (set to False to also return materials with expired EPDs), defaults to True

  • masterformat_filter (list) – Optional list of Masterformat Category names to filter by (ex: [“03 21 00 Reinforcement Bars”]), defaults to []

Usage:
>>> ec3_materials = EC3Materials(bearer_token=token, ssl_verify=False)
>>> ec3_mat_list = ec3_materials.get_materials(params=mat_param_dict)
convert_query_to_mf_string(category_name, field_dict_list, pragma=None)

Converts a dictionary of material search parameters to a pragma string for use in the EC3 API This function includes a POST request that requires an API key with write access

Parameters

  • category_name (str) – EC3 category name (see https://docs.open-epd-forum.org/en/data-format/materials/ for list of valid category names)

  • field_dict_list (list) – List of dictionaries of search parameters (format: [{“field”: “field_name”, “op”: “operator”, “arg”: “argument”}])

  • pragma (list, optional) – List of dictionaries of pragma parameters. Defaults to eMF 2.0/1 and TRACI 2.1.

Returns

string formatted to work with MaterialFilter pragma in EC3 API

Return type

str

get_materials(return_all=False, **params)

Returns matching materials

Parameters

return_all (bool, optional) – Set to True to return all matches. Defaults to False, which will return the quantity specified in max_records.

Returns

List of dictionaries of matching material records

Return type

list

get_materials_mf(category_name, mf_list, return_all=False, **params)

Returns matching materials using filters

Parameters

  • category_name (str) – Open EPD category name (see https://docs.open-epd-forum.org/en/data-format/materials/ for list of valid category names)

  • mf_list (list) – List of dictionaries of search parameters (format: [{“field”: “field_name”, “op”: “operator”, “arg”: “argument”}])

  • return_all (bool, optional) – Set to True to return all matches. Defaults to False, which will return the quantity specified in max_records.

Returns

List of dictionaries of matching material records

Return type

list

get_materials_within_region(postal_code, country_code='US', plant_distance='100 mi', return_all=False, **params)

Returns only materials from plants within provided distance of postal code. This adds the “latitude”, “longitude”, and “plant_distance_lt” keys to your parameter dictionary.

Parameters

  • postal_code (int) – postal code

  • country_code (str, optional) – Two letter country code.. Defaults to ‘US’.

  • plant_distance (str, optional) – Distance to plant with units in string (‘mi’ or ‘km’). Defaults to “100 mi”.

  • return_all (bool, optional) – Set to True to return all matches. Defaults to False, which will return the quantity specified in max_records.

Returns

List of dictionaries of matching material records within distance provided from postal code

Return type

list

get_materials_within_region_mf(category_name, mf_list, postal_code, country_code='US', plant_distance='100 mi', return_all=False, **params)

Returns only materials from plants within provided distance of postal code. This adds the “latitude”, “longitude”, and “plant_distance_lt” keys to your parameter dictionary.

Parameters

  • category_name (str) – Open EPD category name (see https://docs.open-epd-forum.org/en/data-format/materials/ for list of valid category names)

  • mf_list (list) – List of dictionaries of search parameters (format: [{“field”: “field_name”, “op”: “operator”, “arg”: “argument”}])

  • postal_code (int) – postal code

  • country_code (str, optional) – Two letter country code.. Defaults to ‘US’.

  • plant_distance (str, optional) – Distance to plant with units in string (‘mi’ or ‘km’). Defaults to “100 mi”.

  • return_all (bool, optional) – Set to True to return all matches. Defaults to False, which will return the quantity specified in max_records.

Returns

List of dictionaries of matching material records within distance provided from postal code

Return type

list