> ## Documentation Index
> Fetch the complete documentation index at: https://developer.worldly.io/llms.txt
> Use this file to discover all available pages before exploring further.
# MSI Search Materials
## 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.
View recipe
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](/data-dictionary/msi#materialtrimpackage-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.
```json Search parameters theme={null}
{
"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](/data-dictionary/msi#materialtrimpackage-metadata) for details about each parameter.
```json Metadata results theme={null}
{
"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.
```json Version metadata theme={null}
"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](/data-dictionary/msi#impacts) for details about each impact parameter.
```json Aggregate impacts theme={null}
"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](/data-dictionary/msi#category-base-materials-and-processes) 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.
View recipe
## Yield
Yield is returned for materials where the user provided yield for the material.
```json Yield results theme={null}
"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.
```json Search for User Updates theme={null}
{
"platformModifiedBy": "User",
"lastEditedAfter": "2021-01-13T16:38:19.386Z",
"lastEditedBefore": "2021-12-13T20:38:19.386Z"
}
```
## OpenAPI
````yaml api-reference/openapi/msi-api.json POST /search-limited-lcia
openapi: 3.0.0
info:
title: msi-api
version: 1.0.0
servers:
- url: https://api-v2.production.higg.org/msi-api/v1
description: Production
- url: https://api-v2.demo.higg.org/msi-api/v1
description: Demo
security:
- sec0: []
sec1: []
paths:
/search-limited-lcia:
post:
operationId: SearchLimitedLcia
requestBody:
$ref: '#/components/requestBodies/MsiEntityRequest'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/MsiEntityResponseLimited'
components:
requestBodies:
MsiEntityRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/MsiEntityRequest'
required: true
schemas:
MsiEntityResponseLimited:
properties:
results:
items:
$ref: '#/components/schemas/MsiEntityResultLimited'
type: array
msiVersion:
$ref: '#/components/schemas/MsiVersionType'
required:
- msiVersion
- results
type: object
additionalProperties: false
MsiEntityRequest:
properties:
ids:
items:
type: string
type: array
nullable: true
code:
items:
type: string
type: array
nullable: true
name:
type: string
nullable: true
text:
type: string
nullable: true
draft:
type: boolean
nullable: true
sample:
type: boolean
nullable: true
type:
$ref: '#/components/schemas/MsiEntityType'
createdAfter:
type: string
format: date-time
nullable: true
createdBefore:
type: string
format: date-time
nullable: true
lastEditedAfter:
type: string
format: date-time
nullable: true
lastEditedBefore:
type: string
format: date-time
nullable: true
platformModifiedBy:
$ref: '#/components/schemas/PlatformDefault'
platformCreatedBy:
$ref: '#/components/schemas/PlatformDefault'
from:
type: number
format: double
nullable: true
size:
type: number
format: double
nullable: true
type: object
additionalProperties: false
MsiEntityResultLimited:
properties:
baseMaterials:
items:
$ref: '#/components/schemas/BaseMaterialEntityOptionalProcessLimited'
type: array
nullable: true
type: object
additionalProperties: false
MsiVersionType:
properties:
date:
type: string
nextUpdate:
type: string
version:
type: string
required:
- date
- nextUpdate
- version
type: object
additionalProperties: false
MsiEntityType:
enum:
- material
- trim
- packaging
type: string
PlatformDefault:
enum:
- User
- Api
type: string
BaseMaterialEntityOptionalProcessLimited:
properties:
cycles:
$ref: '#/components/schemas/MaterialCyclesLimited'
type: object
additionalProperties: false
MaterialCyclesLimited:
properties: {}
type: object
additionalProperties:
$ref: '#/components/schemas/MaterialCycleResultLimited'
MaterialCycleResultLimited:
properties:
selected:
items:
$ref: '#/components/schemas/MaterialSelectedProcessLimited'
type: array
scores:
$ref: '#/components/schemas/MsiImpactScoresLimited'
detailProcesses:
items:
$ref: '#/components/schemas/DetailProcesses'
type: array
nullable: true
stageName:
type: string
nullable: true
required:
- scores
- selected
type: object
additionalProperties: false
MaterialSelectedProcessLimited:
properties:
scores:
$ref: '#/components/schemas/MsiImpactScoresLimited'
required:
- scores
type: object
additionalProperties: false
MsiImpactScoresLimited:
properties:
impact:
type: number
format: double
globalWarmingPct:
type: number
format: double
eutrophicationPct:
type: number
format: double
waterScarcityPct:
type: number
format: double
abioticDepletionPct:
type: number
format: double
chemistryPct:
type: number
format: double
waterConsumptionPct:
type: number
format: double
biogenicCarbonPct:
type: number
format: double
globalWarmingPts:
type: number
format: double
eutrophicationPts:
type: number
format: double
waterScarcityPts:
type: number
format: double
abioticDepletionPts:
type: number
format: double
chemistryPts:
type: number
format: double
required:
- abioticDepletionPct
- abioticDepletionPts
- biogenicCarbonPct
- chemistryPct
- chemistryPts
- eutrophicationPct
- eutrophicationPts
- globalWarmingPct
- globalWarmingPts
- impact
- waterConsumptionPct
- waterScarcityPct
- waterScarcityPts
type: object
additionalProperties: false
DetailProcesses:
properties:
name:
type: string
id:
type: string
required:
- id
- name
type: object
additionalProperties: false
securitySchemes:
sec0:
type: apiKey
in: header
name: x-api-key
sec1:
type: apiKey
in: header
name: x-developer-request-token
````