Skip to main content

​
Introduction

The Higg MSI API is a JSON query API. All parameters are sent as JSON. The search endpoint can be used to download the full account dataset for processing in the third-party system, or the endpoint can be queried on a number of useful parameters to bring back impacts for specific materials.

​
Search Parameters

To return all data in the account, remove all the search parameters and use {}.
All data including example materials/trims/packages will be returned. The following attributes can be used to query the endpoint.
The materials/trims/packaging that meet all entered criteria will be returned.
See MSI Data Dictionary—Metadata for details about each search parameter. To control the number of results returned and loop through the materials, you can use the from and size fields. The ‘from’ field tells the system which position to pull from. Note that the system starts at position 0. The ‘size’ determines how many materials to return. 
{
  "ids": [
    "string"
  ],
  "code": [
    "string"
  ],
  "name": "string",
  "text": "string",
  "draft": true,
  "sample": true,
  "type": "material",
  "createdAfter": 0,
  "createdBefore": 0,
  "lastEditedAfter": 0,
  "lastEditedBefore": 0,
  "platformCreatedBy":"string",
  "platformModifiedBy":"string",
  "from": 0,
  "size": 0
}

​
Search Results

Extensive information about the material, trim, and package is returned via the Search functionality.
The data returned includes:
• Number of results and their location
• Metadata about the material such as who and when it was created/edited.
• Aggregate impacts
• Process-level impacts for materials
• Yield conversions

​
Metadata Results

Metadata about the material, trim, package are returned.
See MSI Data Dictionary Metadata for details about each parameter. 
{
    "from": 0,
    "size": 1,
    "total": 1,
    "results": [
        {
            "id": "611ffbcc908bc0000a82df78",
            "type": "material",
            "sample": false,
            "draft": false,
            "created": 1629486028720,
            "lastEdited": 1629486028720,
            "name": "Yield Aug 20",
            "code": "yield3",
            "userEmail": "jane.doe@higg.com",
            "platformModifiedBy": "User",
            "platformCreatedBy": "User",
Additionally the current MSI version, date of last update and date of next update will be returned at the bottom of every JSON response when searching for materials. 
    "msiVersion": {
        "date": "1669921200000",
        "nextUpdate": "Q2 2023",
        "version": "3.5"
    }

​
Impacts

Impacts include both Higg MSI normalized scores and Life Cycle Impact Assessment (LCIA) absolute values. The following impacts are included in the Higg MSI API for all example materials, custom materials, acquired materials, sample trims and components, custom trims and components, sample packaging, and custom packaging. The following aggregate, material-level impacts are returned: • Global Warming MSI Score
• Global Warming LCIA value (kg CO2 eq)
• Eutrophication MSI Score
• Eutrophication LCIA value (kg PO4– eq)
• Water Scarcity MSI Score
• Water Scarcity LCIA value (m3)
• Abiotic Resource Depletion, Fossil Fuels MSI Score
• Abiotic Resource Depletion, Fossil Fuels LCIA value (MJ eq)
• Chemistry MSI Score
• Chemistry LCIA value (units)
• Biogenic Carbon Content LCIA value (kg CO2 eq)
• Water Consumption LCIA value (liters)
• MSI total single score [This score is no longer available in the Higg MSI API as of January 2021] See MSI Data Dictionary Impacts for details about each impact parameter. 
"scores": {
                "globalWarming": 15.114249119474671,
                "eutrophication": 0.006025696080364703,
                "waterScarcity": 2.971424237136378,
                "abioticDepletion": 252.60178650939986,
                "chemistry": 19.926823592866178,
                "globalWarmingPts": 14.258782619312404,
                "eutrophicationPts": 6.316243274738611,
                "waterScarcityPts": 1.3630517260591994,
                "abioticDepletionPts": 17.300696358028794,
                "chemistryPts": 9.443919505367068,
                "waterConsumption": 81.65567784773765,
                "biogenicCarbon": 0
            }

​
Category, Base Materials and Processes

See the MSI Data Dictionary for details about each parameter. Category
Category is the material category (Textiles, Leathers, etc). The ‘category’ associated with the baseMaterials result is a system defined material type and is not editable. The custom material category returned at the end of the results, is a user-defined attribute that can be set via the API and does not impact any other features about the material it is helpful for categorizing and filtering. Base Materials/Example Materials
Base materials (which are also the Example Materials) are the top-level type of material. Base Materials are then customized by process cycles/stages (eg cycles/stages are raw material stage, textile formation, dying etc). Cycles
Cycles are the process stages users select to customize materials. The base material uses the default raw material cycle/stage process (for example cotton, fabric can be the base material). The raw material cycle/stage process for the base material can be changed via the API using the processId. For example, changing default ‘cotton, fabric’ to ‘cotton fiber, organic”. The processes must be available for the base material in order to select them. The user can also change additional processes manually in the Higg MSI tool.
By default only the full material and base material impacts are returned via that API. If you would like to retrieve the additional cycle process information for each material, use the API header “show-api-fields”=True. For each cycle, the raw LCIA values are not returned from this endpoint. Instead, for each impact area, the percentage contribution of that impact to the total impact is returned.

​
Yield

Yield is returned for materials where the user provided yield for the material. 
"yieldInfo": [
                {
                    "type": "Yards (linear)",
                    "densityLinear": 3,
                    "densityLinearUnit": "g/m2",
                    "width": 2,
                    "widthUnit": "m",
                    "conversion": 0.0054864
                }
            ]

​
Searching for materials manually updated in MSI

A common use case is to search for materials that have been manually updated by a user in MSI, in order to pull the updated material impacts into the PLM. Users can search for “PlatformModifiedBy”: “User” to find materials updated by users directly in MSI. The “lastEditedAfter”: 0 and “lastEditedBefore”: 0 search parameters can be used to set the date period to search for edits. 
{
    "platformModifiedBy": "User",
    "lastEditedAfter": "2021-01-13T16:38:19.386Z",
    "lastEditedBefore": "2021-12-13T20:38:19.386Z"
}