Authentication

API Authentication (HTTP Basic)

The API uses HTTP Basic Authentication. Your private API token is securely encrypted by the SSL channel.

Calculating the authorization header

Most programming languages encode the authorization header automatically. With HTTP Basic Authentication, the Authorization header is a string containing a Base-64 encoded username and password. In the case of the Catalog API, you need only specify the username as your API key. If your library requires a password, set it to an empty string. Also, ensure that you do not include the 'Basic' keyword as it is not needed in the header. 

"Authorization": Base64Encode(private-api-token)

Additional Request Headers

The API v1 returns results as JSON - javascript object notation. Your requests should always inlude the header requesting the results as JSON:

Accept: application/json

Note: if this header is missing, the API will still return JSON. However, if XML or other format support is enabled in the future, it will be imperative that you include the header to avoid a format mismatch.

Private API Keys

Protect your Private API Keys!
Each Private API key allows access to your account's data. Do not include it anywhere unauthorized users could view it (for example, Javascript).

As mentioned, each Private API Key grants access to a specific interface. You can generate as many private API keys as needed for each interface on your account (most accounts will only have one interface). We recommend that you name each key accordingly and provide an optional description.

Properties

Definition

A property represents a particular attribute of a product (material). Each property is defined by a numeric identifier, a name, an optional unit, and an optional standard (ISO, ASTM, etc.). Properties may also have a list of Searchable Units associated with the property.

Property Data Types

There are multiple property data types defined within the API. Primarily, you will be working with the following types: List, Numeric, NumericRange, and Text.

Property Type: List

A list-based property has a predefined set of values - each one with a corresponding id (ItemId). An example would be the Product Name property which contains a predefined list of product tradenames. List-based properties do not have an associated Unit, UnitId, nor Standard.

Example: List Property (Availability -- 3580)

[
  {
    "PropertyId": 3580,
    "Name": "Availability",
    "Unit": "",
    "UnitId": 0,
    "Standard": null,
    "PropertyType": "List",
    "SearchableUnits": [
      {
        "Key": 0,
        "Value": ""
      }

    ]
  }
]

Property Type: Numeric / NumericRange

Numeric and numeric range properties are virtually similar with one exception: a numeric range data value may either be a range (a to b) or a singular point (a) whereas a numeric data value can singular (a).

Example: NumericRange Property (notched izod impact -- 700)

 [
  {
    "PropertyId": 700,
    "Name": "Notched Izod Impact",
    "Unit": "ft·lb/in",
    "UnitId": 27,
    "Standard": "ASTM D256",
    "PropertyType": "NumericRange",
    "SearchableUnits": [
      {
        "Key": 132,
        "Value": "ft·lb/ft"
      },
      {
        "Key": 27,
        "Value": "ft·lb/in"
      },
      {
        "Key": 497,
        "Value": "ft·lb/mil"
      },
      {
        "Key": 133,
        "Value": "in·lb/ft"
      },
      {
        "Key": 115,
        "Value": "in·lb/in"
      }...
    ]
  }
]

Example: Numeric Property (water absorption -- 4020)

[
  {
    "PropertyId": 4020,
    "Name": "Water absorption",
    "Unit": "%",
    "UnitId": 172,
    "Standard": "ISO 62",
    "PropertyType": "Numeric",
    "SearchableUnits": [
      {
        "Key": 172,
        "Value": "%"
      }
    ]
  }
]

Filters

Definition

A filter is a query that narrows any given search. There are three types of filters that correspond to a property type or general text search: List, Numeric, and Keyword.

List Filter

A list filter is used to filter list-based properties. List-based properties have a predefined set of values - each with a corresponding id (ItemId). This id or list of ids is required in the filter. These ids can be found by performing a search range query.

Example: List Filter (querying all abs materials -- Property: 80, ItemId: 1)

...  
    {
      "Type":			"list",
      "PropertyId":	80,
		"AndSearch":	"false",
      "ItemIds":		[ 1 ]
    }
...

Numeric Filter

A numeric filter is used to filter both numeric and numeric range properties. Required parameters are the PropertyId, UnitId, and either the minimum value (Val1) or the maximum value (Val2). To search for a given range populate both values. To search for all materials with values greater-or-equal-to (≥) use only Val1; and to search for all materials with values less-than-or-equal-to (≤) use only Val2. Finally, to search for a specific data point, set both Val1 and Val2 to the same value.

Note: to find the PropertyId and UnitId query the property [GET /api/v1/property] endpoint. To find a possible range of values, query the search-range endpoint.

Example: Numeric Filter (filter density / specific gravity -- 300)

...
    {
      "Type":       "numeric",
      "PropertyId": 300,
      "UnitId" :    21,
      "Val1":       "2",
      "Val2":       "4" 
    }
 ...

Text Filter

The text filter is used on text-based properties. Required paramerters are the PropertyId, and the Filter's text value.

Example: Text Filter ( searching all materials in the linecard containing "POLY" -- Property: 30260 - Product)

...
    "Filters": [
    {
      "Type":       "text",
      "PropertyId": 30260,
		"ExactMatch": "false",
      "Text":       "POLY"
    }
...

Keyword Filter

The keyword filter performs a text search across a predefined range of general properties including, but not limited to, the following:

supplier, product name, grade, filler, uses, description

Note: there can be only one keyword filter per query.

...
    {
      "Type":       "keyword",
      "Keyword":    "nylon"     
    }
...

Date Filter

The Date filter is used on datetime based properties.: 

...
"Filters": [
  {
    "Type": "date",
    "PropertyId": 87116,
    "MinDate": "10/6/2018",
    "MaxDate": "10/11/2018"
  }
]
...

Value Summary POST

Query Definition

The value-summary api method is a general purpose method that returns data for a particular set of properties and entries (products).

Body Params

language:
string en
The 2-letter ISO code indicating the requested content language
en, de, es, fr, it, ja, pt, ru, zh, zhcn, zhtw
unitSystem:
integer
The requested unit system id for returned values
0 for SI, 1 for English
entryIds:
array [int]
An integer array of the requested product entry ids
propertyIds:
array [int]
An integer array of the requested property ids

Example

For a given set of products (83,85,86,87,89), request SI values for the following properties: Product (30260), Manufacturer / Supplier (100), and Generic Symbol (80) 

{
  "Language": "en",
  "UnitSystem": 0,
  "EntryIds": [
    83,
    85,
    86,
    87,
    89
  ],
  "PropertyIds": [
    30260,
    100,
    80
  ]
}

Search Range POST

Definition

The search-range method returns property-range information for a given query. A property range contains all of the available list values for a list property or the numeric range (min and max) for numeric / numeric-range properties. For example, it can be used to access the product names associated with a particular supplier. This method is commonly used to render product navigation/querying UI.

Body Params

language:
string en
The 2-letter ISO code indicating the requested content language
en, de, es, fr, it, ja, pt, ru, zh, zhcn, zhtw
propertyIds:
array [int]
An integer array of the requested property ids
unitSystem:
integer
The requested unit system id for returned values
0 for SI, 1 for English
filters:
array [filter]
An array of filters. This can be empty or a mix of list, keyword, and numeric filters

Example

Request the list of product lines (40) and suppliers/manufacturers (100) available for all abs products (property id 80 with item id of 1 -- ABS). 

 {
  "Language":       "en",
  "UnitSystem":     0,
  "PropertyIds":    [ 40, 100 ],
  "Filters":        [
                        {
                          "Type": "list",
                          "PropertyId": 80,
								  "AndSearch": "false",
                          "ItemIds": [ 1 ]
                        }
                    ]
}

Search Result POST

Definition

The Search Results method provides a single “page” of sorted results for a particular query. It provides a list of matching products (Entries), along with product data and associated actions (URLs).

Body Params

language:
string en
The 2-letter ISO code indicating the requested content language
en, de, es, fr, it, ja, pt, ru, zh, zhcn, zhtw
unitSystem:
integer
The requested unit system id for returned values
0 for SI, 1 for English
propertyIds:
array [int]
An integer array of the requested property ids
sorts:
array [sort]
An array of sort objects that indicate a property id and sort direction.
page:
integer 1
The requested page of results
pageSize:
integer 25
The requested results per page
filters:
array [filter]
An array of filters. This can be empty or a mix of list, keyword, and numeric filters
removeEmptyProperties:
bool
Removes any empty properties from the results set for a given page. Defaults to false. **NOTE: this is a page by page action, future pages may contain previously removed property.

Example

Request product name and grade (30260), manufacturer / supplier (100), and generic symbol (80) data values for all materials with a notched-izod impact value between 1.5 and 2.3 ft·lb/in. Sort by manufacturer (100) ascending. Request page 1 of 25 results per page. 

{
  "Language": "en",
  "UnitSystem": 0,
  "RemoveEmptyProperties": "false",
  "PropertyIds": [ 30260, 100, 80 ],
  "Sorts": [
    {
      "PropertyId": 100,
      "Ascending": true
    }
  ],
  "Page": 1,
  "PageSize": 25,
  "Filters": [
    {
      "Type": "list",
      "PropertyId": 80,
		"AndSearch": "false",
      "ItemIds": [
        1
      ]
    }
  ]
}

Understanding the Results

There are four main sections to the results data: ResultsSummary, PropertySummary, ActionSummary and Data.
The ResultsSummary section contains page and results information. 

"ResultSummary": {
                    "ResultCount": 74,
                    "RequestedPage": 1,
                    "PageCount": 15
                }

The PropertySummary and ActionSummary sections outline information for the requested properties and actions in the dataset. Both are usesful in building column information. 

  "PropertySummary": [
    {
      "PropertyId": 30260,
      "Name": "Product",
      "Unit": "",
      "UnitId": 0,
      "Standard": null,
      "PropertyType": "Text"
    },
    {
      "PropertyId": 100,
      "Name": "Manufacturer / Supplier",
      "Unit": "",
      "UnitId": 0,
      "Standard": null,
      "PropertyType": "List"
    },
    {
      "PropertyId": 80,
      "Name": "Generic Symbol",
      "Unit": "",
      "UnitId": 0,
      "Standard": null,
      "PropertyType": "List"
    }
  ],
  "ActionSummary": [
    {
      "Name": "Datasheet"
    }
  ],

The Data section provides all the data for the properties and actions requested. 

  "Data": [
    {
      "EntryId": 123589,
      "PropertyData": [
        {
          "PropertyId": 30260,
          "Values": [
            {
              "Value": "Cellidor CP 300-10",
              "Note": ""
            }
          ]
        },
        {
          "PropertyId": 100,
          "Values": [
            {
              "Value": "ALBIS PLASTIC GmbH",
              "Note": ""
            }
          ]
        },
        {
          "PropertyId": 80,
          "Values": [
            {
              "Value": "CAP",
              "Note": ""
            }
          ]
        }
      ],
      "ActionData": [
      ]
    },
...

Datasheet GET

Definition

Response Type: application/pdf

Body Params

language:
string en
The 2-letter ISO code indicating the requested content language
en, de, es, fr, it, ja, pt, ru, zh, zhcn, zhtw
propertySet:
string
The requested property set for teh datasheet
COMBO for Combo Datasheet (default), ASTM for ASTM, ISO for ISO
entryIds:
Array[integer]
The requested entries for datasheet. Passing more than one entryId will return a comparison datasheet.
unitSystem:
int
The unit system id for datasheet.
0 SI, 1 English

Property Set Data Post

Definition

Given an Entry ID or List of Entry ID's, this method returns values found in the datasheet property set.

Body Params

language:
string en
The 2-letter ISO code indicating the requested content language
en, de, es, fr, it, ja, pt, ru, zh, zhcn, zhtw
entryIds:
array [int]
An integer array of the requested entry ids
propertySet:
string
Data property set name
unitSystem:
int
The unit system id for datasheet.
0 SI, 1 English
additionalPropertyIds:
array [int]1
Denotes additional property ids that are not returned by default from the propertysetdata response. The properties returned from this endpoint are found in the body of the datasheet. Other data points, such as the product family (40), grade name (20) are not found in the main body of the datasheet. However, these are pre-configured to be returned in the response. Anything outside these pre-configured properties can be requested using this field

Example

Understanding the Results

The response object has the following fields:

  • CategorySummary
  • PropertySummary
  • ValueSetSummary
  • ActionSummary
  • Data

CategorySummary:

CategorySummary lists the categories/sections that properties map to within a property set. Here is a relatively small set of categories returned from a PE TDS request: 
 "CategorySummary": [
      {
        "Name": "General",
        "Id": 20000
      },
      {
        "Name": "Resin Properties",
        "Id": 20001
      },
      {
        "Name": "Thermal",
        "Id": 20005
      },
      {
        "Name": "Additional Information",
        "Id": 81403
      }
    ],

PropertySummary:

CategoryId corresponds to the category the property maps to with in the property set. In the event it is null, it is because it does not map to a category for the given property set. This is the case for any property requested by AdditionalProperties. 
 "PropertySummary": [
      {
        "PropertyId": 2660,
        "Name": "Product Description",
        "Unit": "",
        "UnitId": 0,
        "Standard": null,
        "PropertyType": "Text",
        "CategoryId": 20000
      },
      {
        "PropertyId": 86044,
        "Name": "Availability",
        "Unit": "",
        "UnitId": 0,
        "Standard": null,
        "PropertyType": "List",
        "CategoryId": 20000
      },
      {
        "PropertyId": 82761,
        "Name": "Additive",
        "Unit": "",
        "UnitId": 0,
        "Standard": null,
        "PropertyType": "List",
        "CategoryId": 20000
      },
      {...}
]

ValueSetSummary:

All TDS datasheet data points are common to the material. This is what we call the default value set or blank ("") as shown in the API response. In the event that a material has multiple values for a single data point, that's where multiple value sets comes in. For example, a material may have both dry and conditioned values specified for a single data point. These specified value types are what we call value sets. ValueSetSummary simply summarizes which value sets are present in the current response. 
"ValueSetSummary": [
    {
      "Key": "Dry",
      "Display": "Dry"
    },
    {
      "Key": "Conditioned",
      "Display": "Conditioned"
    }
  ],

ActionSummary:

This serves the same purpose as it does for the search/result endpoint given above. It summarizes the actions/document types present in the current response. 
 "ActionSummary": [
      {
        "Name": "Datasheet",
        "Key": "LEGACY",
        "PropertySet": "TDS"
      }
    ],

Data:

This serves the same purpose as it does for the search/result endpoint given above. It is an array of entry objects that includes the entry's property data and actions with two additions - GroupId and ValueSet. As all data points are listed in a single array, there needs to be a way to regroup values related to a single data point (think dry and conditioned values for one data point). The values returned for this endpoint include a GroupId to be used for this purpose. Any values listed under a given property that share the same GroupId are related and denote the different value set for a single data point. ValueSet indicates the corresponding value set - e.g. dry or conditioned. 
 "Data": [
      {
        "EntryId": 12345,
        "DatasheetApiUrl": "https://demo.ulprospector.com/api/v1/datasheet?unitSystem=1&language=en&entryIds=12345",
        "PropertyData": [
        {
          "PropertyId": 6380,
          "Values": [
            {
              "ValueSet": "Dry",
              "GroupId": 0,
              "Value": "2840",
              "Note": "-40°C"
            },
            {
              "ValueSet": "Conditioned",
              "GroupId": 0,
              "Value": "3300",
              "Note": "-40°C"
            },
            {
              "ValueSet": "Dry",
              "GroupId": 1,
              "Value": "2300",
              "Note": "23°C"
            },
            {
              "ValueSet": "Conditioned",
              "GroupId": 1,
              "Value": "730",
              "Note": "23°C"
            },
            {
              "ValueSet": "Dry",
              "GroupId": 2,
              "Value": "400",
              "Note": "80°C"
            },
            {
              "ValueSet": "Conditioned",
              "GroupId": 2,
              "Value": "370",
              "Note": "80°C"
            },
            {
              "ValueSet": "Dry",
              "GroupId": 3,
              "Value": "295",
              "Note": "120°C"
            },
            {
              "ValueSet": "Conditioned",
              "GroupId": 3,
              "Value": "220",
              "Note": "120°C"
            },
            {
              "ValueSet": "Dry",
              "GroupId": 4,
              "Value": "250",
              "Note": "150°C"
            },
            {
              "ValueSet": "Conditioned",
              "GroupId": 4,
              "Value": "220",
              "Note": "150°C"
            }
          ]
        },          
]