# Automated Mapping (Get Best Match) ## How to Use the GetBestMatch API The `GetBestMatch` API is designed to help you categorise unstructured input (e.g. from invoices, bills of materials, other datasets) and find the best-matching products and materials based on your input descriptions. This guide explains the required parameters, optional parameters, and how to use the API effectively. *** ### Endpoint **POST** `/api/get_best_match/` *** ### Required Parameters | Parameter | Type | Description | | ------------- | ----------- | ---------------------------------------------------------------- | | `input_items` | `list[str]` | A list of sentences describing the products you are looking for. | #### Example Request ```json { "input_items": [ "Therma Insulation", "Kooltherm K15 FR Panneau Facade" ] } ``` *** ### Optional Parameters These parameters allow you to customize your query to refine the results. #### General Options | Parameter | Type | Description | | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include_product_data` | `boolean` | Include detailed product data in the response. Defaults to `False`. | | `include_material_data` | `boolean` | Include detailed material data in the response. Defaults to `False`. | | `custom_keywords` | `dict` | Dict with keyword mapping to product type and material type. The keywords affect the classification of the input items. Example `{"0/2mm": ["Road construction","Asphalt"], "absorber anchor": ["Metal accessories", "Steel"]}` | ### Filters You can use filters to narrow down your search for products or materials. By filtering, this narrows the range of products or materials that can be mapped, for example to enforce matches to products within a certain region. *** #### Product Filters
FilterExampleDescription
fire_performancefire_performance=['A1', 'B']Filter by fire performance classification; multiple values allowed.
epd_operatorepd_operator=EPDNorgeFilter products by the EPD operator.
norm_pricenorm_price=[1, 2, 3]Filter by norm price IDs.
certificate_typecertificate_type='EPD'Filter by certificate type name.
product_type_familyproduct_type_family='Plastics'Filter by product type family; partial match allowed.
material_type_familymaterial_type_family='Polymers'Filter by material type family; partial match allowed.
certificate_type_familycertificate_type_family='Data Sheets'Filter by certificate type family; partial match allowed.
namename='EcoBrick'Filter by product name; partial match allowed.

*If you're including special characters (like +, &, or =) in filters, be sure to encode them properly, or results may not match as expected.
uuiduuid='abcd1234'Filter by unique product UUID.
declared_unitdeclared_unit='kg'Filter by declared unit in product material facts.
product_typeproduct_type='Insulation'Filter by product type name; partial match allowed.
product_typesproduct_types=['Concrete', 'Wood']Filter by multiple product types.
material_typematerial_type='Steel'Filter by material type name; partial match allowed.
material_typesmaterial_types=['Steel', 'Aluminum']Filter by multiple material types.
building_applicationsbuilding_applications='External walls'Filter by building applications; partial match allowed.
building_typesbuilding_types='Commercial'Filter by building types; partial match allowed.
companycompany='2050 Materials'Filter by company name; partial match allowed.
compliancescompliances='EN 15804'Filter by compliance standard; partial match allowed.
manufacturing_countrymanufacturing_country='Germany'Filter by manufacturing country; partial match allowed.
continentcontinent='Europe'Filter by continent name; partial match allowed.
*** ### Material Filters | Filter | Example | Description | | ----------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `material_name` | `material_name='Concrete'` |

Filter materials by name; partial match allowed.

\*If you're including special characters (like +, &, or =) in filters, be sure to encode them properly, or results may not match as expected.

| | `product_type` | `product_type='Insulation'` | Filter materials by related product type name; partial match allowed. | | `product_types` | `product_types=['Concrete', 'Wood']` | Filter materials by multiple product type names; exact matches required. | | `material_type` | `material_type='Plastic'` | Filter by specific material type name; partial match allowed. | | `material_types` | `material_types=['Steel', 'Aluminum']` | Filter by multiple material types; exact matches required. | | `data_source` | `data_source='2050 Materials Quantity Surveyor Dataset - 2024'` | Filter by the data source name; partial match allowed. | | `data_sources` | `data_sources=['2050 Materials Quantity Surveyor Dataset - 2024', '`ICE DB V3.0`']` | Filter by multiple data source names; exact matches required. | | `source_uuid` | `source_uuid='123e4567-e89b-12d3-a456-426614174000'` | Filter by a specific data source UUID. | | `declared_unit` | `declared_unit='m2'` | Filter by declared unit; case-insensitive exact match. | | `updated_after` | `updated_after='2023-01-01'` | Filter materials updated after a specific date (format: YYYY-MM-DD). | | `updated_before` | `updated_before='2023-12-31'` | Filter materials updated before a specific date (format: YYYY-MM-DD). | | `created_after` | `created_after='2023-01-01'` | Filter materials created after a specific date (format: YYYY-MM-DD). | | `created_before` | `created_before='2023-12-31'` | Filter materials created before a specific date (format: YYYY-MM-DD). | | `updated_between` | `updated_between='2023-01-01,2023-12-31'` | Filter materials updated between two dates (format: YYYY-MM-DD,YYYY-MM-DD). | | `created_between` | `created_between='2023-01-01,2023-12-31'` | Filter materials created between two dates (format: YYYY-MM-DD,YYYY-MM-DD). | *** ### Example Request with Filters ```json { "input_items": [ "Therma Insulation", "Kooltherm K15 FR Panneau Facade" ], "include_product_data": false, "include_material_data": false, "product_filters": { "manufacturing_country": "Netherlands", "product_type": "Insulation (Thermal)" }, "material_filters": { "data_source": "2050 Materials Quantity Surveyor Dataset - 2024", "product_type": "Insulation (Thermal)" } } ``` *** ### API Response The API will return a JSON response containing the best matches for your query. Below is an example response: #### Example Response ```json { "input_items": [ "Therma Insulation", "Kooltherm K15 FR Panneau Facade" ], "results": { "Therma Insulation": { "product_type": "Insulation (Thermal)", "material_type": "PUR (Polyurethane)", "uniclass_systems": [ "Wall covering and finish systems (Ss_25_45)", "Wall insulation systems (Ss_25_45_72)" ], "uniclass_products": [ "Polyurethane (PUR) foam insulation (Pr_25_31_28_67)" ], "uniclass_materials": [ "Polyurethane (PU) (Ma_60_65_93)" ], "product_name": "Therma TR23", "product_company_name": "Kingspan", "product_manufacturing_emissions_intensity_factor": 6.96, "product_manufacturing_emissions_intensity_unit": "m2", "product_manufacturing_emissions_per_kg": 8.220022822195157, "product_url": "https://app.2050-materials.com/product/details_designer/kingspan-therma-tr23", "product_match_score": 0.21212120850880942, "material_name": "Insulation (PU)", "material_manufacturing_emissions_intensity_factor": 5.6, "material_manufacturing_emissions_intensity_unit": "m2", "material_data_source": "2050 Materials Quantity Surveyor Dataset - 2024", "material_id": 24347, "material_match_score": 0.3513513505458832 }, "Kooltherm K15 FR Panneau Facade": { "product_type": "Finish (External floors)", "material_type": "PUR (Polyurethane)", "uniclass_systems": [ "Paving systems (Ss_30_14)", "Wall covering and finish systems (Ss_25_45)", "External floor tiling systems (Ss_30_42_32_30)", "Floor and deck structure systems (Ss_30_12)", "Wall insulation systems (Ss_25_45_72)" ], "uniclass_products": [ "Polyurethane (PUR) foam insulation (Pr_25_31_28_67)" ], "uniclass_materials": [ "Polyurethane (PU) (Ma_60_65_93)" ], "product_name": "Kooltherm\u00ae K15", "product_company_name": "Kingspan", "product_manufacturing_emissions_intensity_factor": 9.1, "product_manufacturing_emissions_intensity_unit": "m2", "product_manufacturing_emissions_per_kg": 7.415332064620465, "product_url": "https://app.2050-materials.com/product/details_designer/kingspan-kooltherm-r-k15", "product_match_score": 0.2888888915379842, "material_name": "Insulation (PU)", "material_manufacturing_emissions_intensity_factor": 5.6, "material_manufacturing_emissions_intensity_unit": "m2", "material_data_source": "2050 Materials Quantity Surveyor Dataset - 2024", "material_id": 24347, "material_match_score": 0.15853658318519592 } } } ``` *** This guide will help you make the most out of the `GetBestMatch` API by understanding its input parameters, filters, and response format