Automated Mapping

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

{
  "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

Filter	Example	Description
fire_performance	fire_performance=['A1', 'B']	Filter by fire performance classification; multiple values allowed.
norm_price	norm_price=[1, 2, 3]	Filter by norm price IDs.
certificate_type	certificate_type='EPD'	Filter by certificate type name.
product_type_family	product_type_family='Plastics'	Filter by product type family; partial match allowed.
material_type_family	material_type_family='Polymers'	Filter by material type family; partial match allowed.
certificate_type_family	certificate_type_family='Data Sheets'	Filter by certificate type family; partial match allowed.
name	name='EcoBrick'	Filter by product name; partial match allowed.
uuid	uuid='abcd1234'	Filter by unique product UUID.
declared_unit	declared_unit='kg'	Filter by declared unit in product material facts.
product_type	product_type='Insulation'	Filter by product type name; partial match allowed.
product_types	product_types=['Concrete', 'Wood']	Filter by multiple product types.
material_type	material_type='Steel'	Filter by material type name; partial match allowed.
material_types	material_types=['Steel', 'Aluminum']	Filter by multiple material types.
building_applications	building_applications='External walls'	Filter by building applications; partial match allowed.
building_types	building_types='Commercial'	Filter by building types; partial match allowed.
company	company='2050 Materials'	Filter by company name; partial match allowed.
compliances	compliances='EN 15804'	Filter by compliance standard; partial match allowed.
manufacturing_country	manufacturing_country='Germany'	Filter by manufacturing country; partial match allowed.
continent	continent='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.
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

{
  "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

{
  "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