Skip to main content

Expanding search results

This document covers the configuration of the data returned by the Partium Find API.

With network latency and bandwidth considerations in mind, the API was designed with a customizable response object format to ensure that only the necessary data is transferred back to you.

To configure this, simply set the projection field in the search request, specifying the list of fields you wish to include in the result.

Possible values are:

  • results.id: The unique id of the part, as it appears in the catalog.
  • results.partiumId: The unique id of the part in the Partium system. It is generated by Partium during ingestion.
  • results.name: The name of the part in the specified search language. If the specified language is unavailable, the name will be returned in the first available fallback language. For more information about fallback languages, please refer to the Fallback languages article.
  • results.nameLanguage: The language code of the part name. This will correspond to the specified search language or the fallback language used.
  • results.previewData: Custom data ingested into Partium. This field can be used if you need any additional information in the result list. See Preview Data below for more information.
  • results.images: Links and details for the images available for this part, in various sizes. See Images below for more information.
  • results.mountingLocationsCount: The count of spots where this part appears in the BOM.
  • results.createdAt: The date and time the record was created in the Partium system.
  • results.modifiedAt: The date and time the record was last modified in the Partium system.
  • results.attributes: Structured metadata about parts, including translated labels and values. See Attributes below for more information.
  • results.highlights: Information showing where the user's search query text matches different parts of the search results. This helps improve search experience by visually highlighting exactly where and how the search terms appear in the results. For detailed information, please refer to the Highlighting results article.
> POST https://api.partium.io/1/find/search
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
> Content-Length: 417
>
> {
>   "language": "en",
>   "projection": [
>     "smartFilters",
>     "results.id",
>     "results.partiumId",
>     "results.name",
>     "results.nameLanguage",
>     "results.previewData",
>     "results.images",
>     "results.mountingLocationsCount",
>     "results.createdAt",
>     "results.modifiedAt",
>     "results.attributes"
>   ],
>   "matches": {
>      "organization": "<<Your Organization Name>>",
>      "exact": "PM19239.AD"
>   }
> }
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 2224
<
< {
<   "sessionId": "cfaac7fc-8c0a-420a-b6ee-f59396861753",
<   "imageId": null,
<   "results": [
<     {
<       "id": "PM19239.AD",
<       "name": "HERRINGBONE GEAR 25 millimetre",
<       "nameLanguage": "en",
<       "partiumId": "c9c340a9-1679-47ee-8645-0e1f1a3a6258",
<       "previewData": {
<         "price": "500.31 USD"
<       },
<       "images": [
<         {
<           "partiumId": "44b758df-8e88-457f-8626-ff71cbff11cf",
<           "expireAt": "2024-05-07T10:34:40.339417",
<           "urls": {
<             "thumbnail": "https://cdn.cloudfront.com/idfhad25643/thumbnail.jpg",
<             "small": "https://cdn.cloudfront.com/idfhad25643/small.jpg",
<             "medium": "https://cdn.cloudfront.com/idfhad25643/medium.jpg",
<             "original": "https://cdn.cloudfront.com/idfhad25643/original.jpg"
<           },
<           "description": "IMG_TOP.jpg"
<         },
<         {
<           "partiumId": "6c9e2ad5-44c2-4cb7-968a-3dfe27c7e979",
<           "expireAt": "2024-05-07T10:34:40.339417",
<           "urls": {
<             "thumbnail": "https://cdn.cloudfront.com/ddfaisa2165uhdufha/thumbnail.png",
<             "small": "https://cdn.cloudfront.com/ddfaisa2165uhdufha/small.png",
<             "medium": "https://cdn.cloudfront.com/ddfaisa2165uhdufha/medium.png",
<             "original": "https://cdn.cloudfront.com/ddfaisa2165uhdufha/original.png"
<           },
<           "description": "IMG_COVER.png"
<         }
<       ],
<       "mountingLocationsCount": 2,
<       "createdAt": "2024-02-23T13:54:55.270Z",
<       "modifiedAt": "2024-02-23T13:54:55.270Z",
<       "attributes": [
<         {
<           "label": "Category",
<           "language": "en",
<           "values": ["Gears"]
<         },
<         {
<           "label": "Manufacturer",
<           "language": "en",
<           "values": ["Gears & Shafts co."]
<         }
<       ]
<     }
<   ],
<   "smartFilters": [
<     {
<       "label": "Category",
<       "values": [
<         {
<           "value": "Gears",
<           "count": 12653
<         }
<       ]
<     },
<     {
<       "label": "Manufacturer",
<       "values": [
<         {
<           "value": "Gears & Shafts co.",
<           "count": 153
<         },
<         {
<           "value": "ACME Funding & Holding LCA.",
<           "count": 164
<         }
<       ]
<     }
<   ]
< }
note

Replace <<Your Organization Name>> with the provided organization name.

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

Additional Details​

This section provides detailed information about specific projection fields.

Images​

The results.images field provides access to all images associated with a part. Each image entry includes:

  • partiumId: Unique identifier for the image in the Partium system
  • expireAt: Timestamp when the image URLs will expire
  • description: Text description of the image
  • urls: Object containing URLs for different image sizes:
    • thumbnail: Small preview image
    • small: Medium-sized image
    • medium: Larger image
    • original: Full resolution image, as ingested in the system

Considerations​

  • Image URLs are temporary and will expire at the specified expireAt timestamp
  • The original image URL may be significantly larger than other sizes
  • Some sizes may not be available for all images, for which null is returned.

Common Use Cases​

  • Displaying part thumbnails in search results
  • Showing detailed product images in part details view
  • Creating image galleries for parts
  • Using images for visual part identification

Troubleshooting​

Expired URLs

  • Image URLs are temporary and will expire at the specified expireAt timestamp
  • Implement URL refresh logic before the expiration time
  • Consider caching the URLs and implementing a refresh mechanism

Missing Image Sizes

  • Some image sizes might not be available for all images
  • Always check for null values in the urls object
  • Implement fallback logic to use alternative sizes when preferred ones are missing

Preview Data​

The results.previewData field contains custom data that has been ingested into Partium for your organization. This field is particularly useful for storing additional information that is not relevant for the searching capabilities but has to be displayed in the results list.

note

Including results.previewData in your projection may significantly increase the response payload size, depending on the organization catalog data. Consider using pagination to manage large result sets efficiently.

Structure​

The preview data is returned as a free scheme JSON object, accodingly to the organization needs.

Considerations​

  • The available fields and their structure are specific to the organization
  • Fields may be empty or missing for some parts
  • Values are returned as-is from the ingestion process

Common Use Cases​

  • Storing pricing information
  • Including technical specifications
  • Adding custom metadata
  • Storing external system references

Troubleshooting​

Missing Fields

  • Fields may be missing or null for some parts
  • Always implement null checks in your application
  • Consider providing default values for missing fields

Inconsistent Data Structure

  • The structure of preview data can vary between parts
  • Implement defensive programming to handle varying field names and structures
  • Consider validating the data structure before processing

Attributes​

The results.attributes field provides detailed attribute information for each search result. Each attribute includes:

  • label: The translated label of the attribute
  • language: The language code of the translated content
  • values: Array of attribute values
note

Including results.attributes in your projection may significantly increase the response payload size, especially when dealing with parts that have many attributes, depending on the organization catalog data. Consider using pagination to manage large result sets efficiently.

The attributes are returned in the language specified in your search request's language field. If the requested language is not available for a particular attribute, the system will fall back to the first available language from your fallbackLanguages list. If no fallback languages are specified, the organization's default fallback languages will be used. For more information about fallback languages, please refer to the Fallback languages article.

Considerations​

  • Values are always returned as an array, even for attributes with a single value.
  • Attribute labels and values are translated to the requested language when available.
  • Each attribute may be returned in a different language depending on what translations exist in the organization's catalog.
  • The values for an attribute will always be in the same language as its label.
  • Values may be returned as null if they are not available in the desired language.

Common Use Cases​

  • Part categorization and filtering
  • Manufacturer details retrieval
  • Installation instructions access
  • Technical specifications
  • Part identification and classification

Notes​

  • The attributes returned are specific to the selected organization's catalog.
  • Existing attribute values are always returned as strings, even for numeric values.

Examples​

Here are examples of different attribute types and values you might encounter, showing how attributes can appear in different languages:

{
  "attributes": [
    {
      "label": "Abmessungen",
      "language": "de",
      "values": ["Länge: 100mm", "Breite: 50mm", "Höhe: 25mm"]
    },
    {
      "label": "Material",
      "language": "en",
      "values": ["Stainless Steel 304", "Aluminum Alloy"]
    },
    {
      "label": "Gewicht",
      "language": "de",
      "values": ["2,5 kg"]
    },
    {
      "label": "Operating Temperature",
      "language": "en",
      "values": ["-20°C to +80°C"]
    },
    {
      "label": "Certifications",
      "language": "en",
      "values": ["ISO 9001", "CE", "RoHS"]
    },
    {
      "label": "Installation Instructions",
      "language": "en",
      "values": ["See manual page 45", "Requires M8 bolts"]
    },
    {
      "label": "Warranty Information",
      "language": "en",
      "values": [null]
    }
  ]
}

This example demonstrates:

  • Multi-value attributes (Material, Certifications, ...)
  • Numeric values as strings (Weight)
  • Instructional text (Installation Instructions)
  • Mixed language responses (en, de), for when some of the attributes are missing translations
  • Null values (Warranty Information), for when the value is missing in the desired language

Troubleshooting​

Missing Attributes

  • If an attribute is missing from the response, it means it's not defined for the part in the catalog
  • Null values in the array ("values": [null]) indicate that the value exists but is not available in the requested language

Language Handling

  • If an attribute appears in a different language than requested, it means the translation is not available
  • Check the language field of each attribute to determine which language is being used
  • Implement fallback language handling in your application. To enhance user experience, consider adding visual indicators when content is displayed in a fallback language rather than the requested one.

Data Type Handling

  • All attribute values are returned as strings, even for numeric values
  • Implement proper type conversion in your application when working with numeric values, if needed

Performance Considerations

  • Large response payloads can impact performance
  • Use pagination when dealing with large result sets
  • Cache frequently accessed data when possible