> For the complete documentation index, see [llms.txt](https://docs.2050-materials.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.2050-materials.com/readme/using-the-2050-materials-api/available-endpoints/automated-mapping-get-best-match.md).

# 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** `https://app.2050-materials.com/developer/api/get_best_match/`

Send the token in the header `Authorization: Bearer <api_token>`.

***

### 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"]}` |
| `split_components`      | `boolean` | Split each input item into its components and match each one. Matched components are returned in a `components` list on the result, each with a `component_name` and the same fields as the result. Defaults to `false`.        |

### 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.

Put product filters in the `product_filters` object and material filters in the `material_filters` object of the request body (both JSON objects). The tables below show the keys and example values to put in those objects.

* `sort_by`, `sort_order`, `group_by`, `data`, `page` and `page_size` are not accepted in either object and return 400.
* `functional_unit` is accepted only in `product_filters` (e.g. `"functional_unit": "m2"`). It limits product matches to products that can be converted to that unit and, with `include_product_data`, rescales the embedded `product_data` to that unit. In `material_filters` it returns 400.

***

#### Product Filters

<table><thead><tr><th width="171">Filter</th><th width="215">Example</th><th>Description</th></tr></thead><tbody><tr><td><code>fire_performance</code></td><td><code>fire_performance=['A1', 'B']</code></td><td>Filter by fire performance class, exact match; multiple values allowed.</td></tr><tr><td><code>epd_operator</code></td><td><code>epd_operator=EPDNorge</code></td><td>Filter products by the EPD operator; case-insensitive partial match, single value.</td></tr><tr><td><code>norm_price</code></td><td><code>norm_price=[1, 2, 3]</code></td><td>Filter by norm price, using the id or the label (e.g. <code>'££'</code>) from <code>get_product_filters</code>.</td></tr><tr><td><code>certificate_type</code></td><td><code>certificate_type='EPD'</code></td><td>Filter by certificate type name.</td></tr><tr><td><code>product_type_family</code></td><td><code>product_type_family='Plastics'</code></td><td>Filter by product type family; partial match allowed.</td></tr><tr><td><code>material_type_family</code></td><td><code>material_type_family='Polymers'</code></td><td>Filter by material type family; partial match allowed.</td></tr><tr><td><code>certificate_type_family</code></td><td><code>certificate_type_family='Data Sheets'</code></td><td>Filter by certificate type family; partial match allowed.</td></tr><tr><td><code>name</code></td><td><code>name='EcoBrick'</code></td><td>Filter by product name; partial match allowed.<br><br>*<em>If you're including special characters (like +, &#x26;, or =) in filters, be sure to encode them properly, or results may not match as expected.</em></td></tr><tr><td><code>unique_product_uuid_v2</code></td><td><code>unique_product_uuid_v2='ac22f2a4-f960-11ed-92ea-0242ac120004'</code></td><td>Filter by unique product UUID.</td></tr><tr><td><code>declared_unit</code></td><td><code>declared_unit='kg'</code></td><td>Filter by declared unit in product material facts.</td></tr><tr><td><code>product_type</code></td><td><code>product_type='Insulation'</code></td><td>Filter by product type name; partial match allowed.</td></tr><tr><td><code>product_types</code></td><td><code>product_types=['Concrete', 'Wood']</code></td><td>Filter by multiple product types.</td></tr><tr><td><code>material_type</code></td><td><code>material_type='Steel'</code></td><td>Filter by material type name; partial match allowed.</td></tr><tr><td><code>material_types</code></td><td><code>material_types=['Steel', 'Aluminum']</code></td><td>Filter by multiple material types.</td></tr><tr><td><code>building_applications</code></td><td><code>building_applications='External walls'</code></td><td>Filter by building applications; partial match allowed.</td></tr><tr><td><code>building_types</code></td><td><code>building_types='Commercial'</code></td><td>Filter by building types; partial match allowed.</td></tr><tr><td><code>company</code></td><td><code>company='2050 Materials'</code></td><td>Filter by company name; partial match allowed.</td></tr><tr><td><code>compliances</code></td><td><code>compliances='EN 15804'</code></td><td>Filter by compliance standard; case-insensitive partial match, single value.</td></tr><tr><td><code>manufacturing_country</code></td><td><code>manufacturing_country='Germany'</code></td><td>Filter by manufacturing country; partial match allowed.</td></tr><tr><td><code>continent</code></td><td><code>continent='Europe'</code></td><td>Filter by continent name; partial match allowed.</td></tr></tbody></table>

***

### Material Filters

| Filter                                                        | Example                                                                          | Description                                                                                                                                                                                                                 |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `material_name`                                               | `material_name='Concrete'`                                                       | <p>Filter materials by name; partial match allowed.<br><br><em>\*If you're including special characters (like +, &, or =) in filters, be sure to encode them properly, or results may not match as expected.</em></p>       |
| `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 types: names (case-insensitive partial match) or ids.                                                                                                                                  |
| `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: names (case-insensitive partial match) or ids.                                                                                                                                           |
| `data_source`                                                 | `data_source=['2050 Materials Quantity Surveyor Dataset - 2024', 'ICE DB V3.0']` | Filter by data source: one name or a list of names (each a case-insensitive partial match, any of them), or ids.                                                                                                            |
| `source_uuid`                                                 | `source_uuid='123e4567-e89b-12d3-a456-426614174000'`                             | Filter by data source UUID; case-insensitive partial match.                                                                                                                                                                 |
| `declared_unit`                                               | `declared_unit='m2'`                                                             | Filter by declared unit; case-insensitive partial match, or unit id.                                                                                                                                                        |
| `updated_after`                                               | `updated_after='2023-01-01'`                                                     | Filter materials updated strictly after a specific date (format: YYYY-MM-DD).                                                                                                                                               |
| `updated_before`                                              | `updated_before='2023-12-31'`                                                    | Filter materials updated strictly before a specific date (format: YYYY-MM-DD).                                                                                                                                              |
| `created_after`                                               | `created_after='2023-01-01'`                                                     | Filter materials created strictly after a specific date (format: YYYY-MM-DD).                                                                                                                                               |
| `created_before`                                              | `created_before='2023-12-31'`                                                    | Filter materials created strictly 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).                                                                                                                                                 |
| `compliances`                                                 | `compliances='EN 15804+A2'`                                                      | Filter by a stated compliance standard; case-insensitive partial match, one value or a list.                                                                                                                                |
| `geographical_scope`                                          | `geographical_scope=['DE', 'AT']`                                                | Filter by the stated location code (ISO 3166 or regional, e.g. `RER`, `GLO`); exact case-insensitive match. A country name matches its code.                                                                                |
| `data_year__min`, `data_year__max`                            | `data_year__min=2020`                                                            | Filter by the dataset's reference year, inclusive.                                                                                                                                                                          |
| `valid_until_year__min`, `valid_until_year__max`              | `valid_until_year__min=2028`                                                     | Filter by the year the dataset is valid until, inclusive.                                                                                                                                                                   |
| `certificate_subtype`                                         | `certificate_subtype='generic'`                                                  | Generic, Average, Representative, Specific or Template Dataset; case-insensitive. Any other value returns 400.                                                                                                              |
| `epd_operator`                                                | `epd_operator='IBU'`                                                             | Filter by the stated EPD operator; case-insensitive partial match.                                                                                                                                                          |
| `lca_database`                                                | `lca_database='ecoinvent'`                                                       | Filter by the stated LCA database; case-insensitive partial match.                                                                                                                                                          |
| `verification_type`                                           | `verification_type='external'`                                                   | Filter by the stated verification type; case-insensitive partial match.                                                                                                                                                     |
| `uniclass_systems`, `uniclass_products`, `uniclass_materials` | `uniclass_systems='Ss_25_45_72'`                                                 | Filter by Uniclass code or name, through the material's product type and material type. Every product type of the material is checked; the output fields show only the first one's codes. A list matches any of its values. |

***

### 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. `results` is keyed by input item. Each result has:

* `classification`: the predicted `product_type`, `material_type`, `uniclass_systems`, `uniclass_products` and `uniclass_materials`.
* `quantity_info`: quantity details read from the input text, present only when the input contains them.
* `best_product`: the best-matching product: `product_name`, `product_company_name`, `product_manufacturing_emissions_intensity_factor` (fossil A1-A3, kg CO2e per `product_manufacturing_emissions_intensity_unit`), `product_manufacturing_emissions_per_kg`, `product_url` and `product_match_score`. With `include_product_data`, it also holds `product_data`, the full product record as returned by `/get_products`.
* `best_material`: the best-matching generic material: `material_name`, `material_manufacturing_emissions_intensity_factor` (A1-A3, kg CO2e per `material_manufacturing_emissions_intensity_unit`), `material_data_source`, `material_id` and `material_match_score`. With `include_material_data`, it also holds `material_data`, the full material record as returned by `/get_generic_materials`.

Empty `classification` and `quantity_info` objects are left out. When nothing matches, the fields inside `best_product` or `best_material` are `null`. Below is an example response:

#### Example Response

```json
{
  "input_items": [
      "Therma Insulation",
      "Kooltherm K15 FR Panneau Facade"
  ],
  "results": {
      "Therma Insulation": {
          "classification": {
              "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)"
              ]
          },
          "best_product": {
              "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
          },
          "best_material": {
              "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": {
          "classification": {
              "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)"
              ]
          },
          "best_product": {
              "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
          },
          "best_material": {
              "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
