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

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

PreviousGeneric Material Data NextEarly-Stage Embodied Carbon Model

Last updated 1 month ago