Part images

Images are identified by an image_id. These IDs must be unique within a catalog.

In Partium, images are used for two tasks. Images can be used as reference images to enhance the Partium image search and can be displayed in the UI to describe part types. Each image belongs to exactly one part type but part types can contain multiple images.

Reference images are used by the Partium system to identify part types. Multiple images can be added to a part type to enhance the image search.

See What kind of part pictures can be used as reference images

Display images are displayed with the corresponding part in the user interface. Multiple images can be added to a part type.

The purpose of an image is defined by the info field in the image description. The info field contains a list of tokens that the system can use to determine for what the image is used for. The exact meaning of the field depends on the individual catalog configuration but usually the following standard configuration is used:

Info-Value	Description
`searchable`	Image is a reference used for searching
`display`	Image is displayed in the UI
`searchable display`	Both

Order of display images

The order of display images can optionally be defined by adding a position=x token to the info field, where:

x is an integer value.
negative values are not allowed
the lowest allowed value is 0

Example: info="display position=3"

Images with lower position values are displayed before images with higher values.
position=0 is the lowest allowed value, therefore in that case the image will be displayed first.
if the same position value is assigned to multiple images, they will be sorted alphabetically by image_id.
The position cannot be set if the info field does not include the display token.

note

There is a maximum number of images displayed in the UI. In the standard catalog configuration, the maximum is 5. If more than the maximum number of display images are defined for a part, the system selects images to be displayed.

Images with higher position values are discarded first.
If there are images with the same position value:
The system discards images while the number of images is above the maximum and it tries to maintain evenly spaced gaps within the sorted list of images with the same position value.

Creating or updating part images

POST /1/catalog/images

Multiple images can be created and/or updated in one call by specifying a list of definitions in images and a list of image files. The endpoint returns a list of ids of images, which have been created and a list of updated ids. The result contains also an error dictionary in case some images could not be created with corresponding error descriptions.

note

Unlike other upsert operations, this endpoint expects a request of type multipart/form-data because the image file data is attached to the search request payload.

note

This endpoint will respond with error code 503 when the catalog API is in maintenance mode.

Parameter	Value
`images`	List of image definitions
`files`	List of image file parts

images contains a list of image definitions. Each image definition must contain the following fields:

Parameter	Value
`image_id`	Unique id of the image in the catalog
`part_id`	Id of the part type to which this image belongs
`info`	Meta data information to define the purpose of this image.

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/images
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: multipart/form-data; boundary=549844d5-2a2e-4006-8ba9-6ca3423e3fa0
>
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0
> Content-Disposition: form-data; name="images"
> Content-Type: application/json
>
> [
>   {
>     "image_id": "image1",
>     "part_id": "part1",
>     "info": "searchable display"
>   },
>   {
>     "image_id": "image2",
>     "part_id": "part1",
>     "info": "display"
>   }
> ]
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0
> Content-Disposition: form-data; name="files"; filename="image1.jpg"
> Content-Type: image/jpeg
>
> <<your image binary content 1>>
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0
> Content-Disposition: form-data; name="files"; filename="image2.jpg"
> Content-Type: image/jpeg
>
> <<your image binary content 2>>
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0--
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "created": ["image1", "image2"],
<   "updated": [],
<   "errors": {}
< }

response = requests.post(
  'https://api.partium.io/1/catalog/images',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  files=[
    ('files', your_image_binary_content_1, 'image/jpeg'),
    ('files', your_image_binary_content_2, 'image/jpeg')
  ],
  data={
    "images": json.dumps([
      {
        "image_id": "image1",
        "part_id": "part1",
        "info": "searchable display"
      },
      {
        "image_id": "image2",
        "part_id": "part1",
        "info": "display"
      }
    ]
  }
)

let data = new FormData();
data.append('images', JSON.stringify([
  {
    "image_id": "image1",
    "part_id": "part1",
    "info": "searchable display"
  },
  {
    "image_id": "image2",
    "part_id": "part1",
    "info": "display"
  }
]));
data.append('files', new Blob(your_image_binary_content_1, {type: 'image/jpeg'}));
data.append('files', new Blob(your_image_binary_content_2, {type: 'image/jpeg'}));

fetch('https://api.partium.io/1/catalog/images', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: data,
}).then(res => {
  ...
});

note

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

Deleting part images

DELETE /1/catalog/images

Multiple images can be deleted in one call by specifying a list of image ids. The endpoint returns a list of ids of images, which have been deleted. The result contains also an error dictionary in case some images could not be deleted with corresponding error descriptions.

note

This endpoint will respond with error code 503 when the catalog API is in maintenance mode.

🡢 See API Reference

HTTP
Python
JavaScript

> DELETE https://api.partium.io/1/catalog/images
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
> ["image1"]
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "deleted": ["image1"],
<   "errors": {}
< }

response = requests.delete(
  'https://api.partium.io/1/catalog/images',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json=["image1"]
)

fetch('https://api.partium.io/1/catalog/parts', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: ["image1"]
}).then(res => {
  ...
});

note

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

Listing part images

POST /1/catalog/images/list

Query a list of image descriptions. The list can be filtered by specifying a list of part_ids. A paging mechanism can be used to fetch more data if the number of results exceeds the paging limit.

Parameter	Value
`query.part_ids`	Optional list of part_ids to which the images belong
`paging.limit`	Maximum number of results returned by the endpoint
`paging.last_object_id`	Use this id to get the next page of results. The id is returned by a previous call to this endpoint
`projection`	Optional list of fields to be included in the response. Possible values: `part_id`, `info`

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/parts/list
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
>{
>  "paging": {
>    "limit": 10
>  },
>  "projection": ["part_id", "info"]
>}
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "result": [
<     {
<       "image_id": "image1",
<       "part_id": "part1",
<       "info": "searchable display"
<     },
<     {
<       "image_id": "image2",
<       "part_id": "part1",
<       "info": "display"
<     }
<   ],
<   "last_object_id": "unique_object_id",
<   "more_data": false
< }

response = requests.post(
  'https://api.partium.io/1/catalog/parts/list',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json={
    "paging": {
      "limit": 10
    },
    "projection": ["part_id", "info"]
  }
)

fetch('https://api.partium.io/1/catalog/parts/list', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "paging": {
      "limit": 10
    },
    "projection": ["part_id", "info"]
  }
}).then(res => {
  ...
});

note

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

more_data in the response is true indicates that there are more results to fetch. In that case use the returned last_object_id as a parameter for the next call to fetch the next page of results. Repeat this until more_data is false.

Fetching image descriptions by ID

POST /1/catalog/images/select

Fetch a list of image descriptions by specifying a list of image ids.

Parameter	Value
`image_ids`	List of ids of images to fetch
`projection`	Optional list of fields to be included in the response. Possible values: `part_id`, `info`

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/images/select
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
>{
>  "image_ids": ["image1", "image2"],
>  "projection": ["part_id", "info"]
>}
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< [
<   {
<     "image_id": "image1",
<     "part_id": "part1",
<     "info": "searchable display"
<   },
<   {
<     "image_id": "image2",
<     "part_id": "part1",
<     "info": "display"
<   }
< ]

response = requests.post(
  'https://api.partium.io/1/catalog/images/select',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json={
    "image_ids": ["image1", "image2"],
    "projection": ["part_id", "info"]
  }
)

fetch('https://api.partium.io/1/catalog/images/select', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "part_ids": ["image1", "image2"],
    "projection": ["part_id", "info"]
  }
}).then(res => {
  ...
});

note

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

Getting one image description

POST /1/catalog/images/{image_id}

Get the description of one image by specifying an image_id.

Parameter	Value
`image_id`	Unique ID of an image to fetch

🡢 See API Reference

HTTP
Python
JavaScript

> GET https://api.partium.io/1/catalog/image/image1
> Authorization: Bearer <<Your Access Token or API Key>>
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "image_id": "image1",
<   "part_id": "part1",
<   "info": "searchable display"
< }

response = requests.get(
  'https://api.partium.io/1/catalog/images/image1',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  }
)

fetch('https://api.partium.io/1/catalog/images/image1', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  }
}).then(res => {
  ...
});

note

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

Getting one image file

POST /1/catalog/images/{image_id}/original

Get the original image file that was uploaded of one image by specifying an image_id.

Parameter	Value
`image_id`	Unique ID of an image to fetch

🡢 See API Reference

HTTP
Python
JavaScript

> GET https://api.partium.io/1/catalog/image/image1/original
> Authorization: Bearer <<Your Access Token or API Key>>
>
< HTTP/1.1 200 OK
< Content-Type: image/jpeg
<
< <<binary_image_data>>

response = requests.get(
  'https://api.partium.io/1/catalog/images/image1/original',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  }
)

fetch('https://api.partium.io/1/catalog/images/image1/orignal', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  }
}).then(res => {
  ...
});

note

Replace image1 in the example above with the actual ID of the image file to be queried.

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

Order of display images​

Creating or updating part images​

Deleting part images​

Listing part images​

Fetching image descriptions by ID​

Getting one image description​

Getting one image file​

Order of display images

Creating or updating part images

Deleting part images

Listing part images

Fetching image descriptions by ID

Getting one image description

Getting one image file