Paginating search results

This page covers how to paginate search results to reduce bandwidth usage and enhance the user experience.

Pagination is achieved by initiating a new search, and then retrieving the state of that search for each page of results needed.

note

Refer to the API reference for additional details on how to create a search and retrieve its state.

When creating a new search, set the resultOptions.limit field to the desired maximum number of results to retrieve. For instance, to limit results to 5, set the field accordingly:

HTTP
Python
JavaScript

> POST https://api.partium.io/1/find/search
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
> Content-Length: 282
>
> {
>   "language": "en",
>   "projection": [
>     "results.id",
>     "results.partiumId",
>     "results.name",
>     "results.createdAt",
>     "results.modifiedAt"
>   ],
>   "matches": {
>     "organization": "partium-demo-reemtsma",
>     "text": "fan"
>   },
>   "resultOptions": {
>     "limit": 5
>   }
> }
> 
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 971
<
< {
<     "sessionId": "ff6d1393-7279-4045-a265-33d9b311bcaa",
<     "imageId": null,
<     "results": [
<         {
<             "id": "RM5119150",
<             "partiumId": "fa41fbee-7eab-478a-b21b-64c40c14d72d",
<             "name": "FAN",
<             "createdAt": "2023-06-27T15:46:26.770379Z",
<             "modifiedAt": "2024-02-16T15:17:19.203280Z"
<         },
<         {
<             "id": "RM5205317",
<             "partiumId": "0fb4304a-5207-48ff-981a-32eea52831ce",
<             "name": "Fan",
<             "createdAt": "2023-06-27T15:50:13.405761Z",
<             "modifiedAt": "2024-02-16T15:40:16.779312Z"
<         },
<         {
<             "id": "RDC35320",
<             "partiumId": "a91e8b0c-2ed0-4895-bf53-c0fa6fde681d",
<             "name": "Fan A60D88F92",
<             "createdAt": "2023-06-27T15:42:13.423181Z",
<             "modifiedAt": "2024-02-16T12:31:36.988284Z"
<         },
<         {
<             "id": "RDC28113",
<             "partiumId": "bf5d9ca6-3410-4374-9b88-ce063601927b",
<             "name": "Fan wheel",
<             "createdAt": "2023-06-27T15:40:24.384845Z",
<             "modifiedAt": "2024-02-16T12:24:36.082156Z"
<         },
<         {
<             "id": "RDC33819",
<             "partiumId": "2af323d9-fae3-4975-a343-82474a7dcd08",
<             "name": "TEL supply air fan",
<             "createdAt": "2023-06-27T15:41:49.843958Z",
<             "modifiedAt": "2024-02-16T12:30:06.308226Z"
<         }
<     ],
<     "resultsTotalCount": 500
< }

response = requests.post(
  'https://api.partium.io/1/find/search',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json={
    "language": "en",
    "projection": [
      "results.id",
      "results.partiumId",
      "results.name",
      "results.createdAt",
      "results.modifiedAt"
    ],
    "matches": {
      "organization": "partium-demo-reemtsma",
      "text": "fan"
    },
    "resultOptions": {
      "limit": 5
    }
  },
)

fetch('https://api.partium.io/1/find/search', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "language": "en",
    "projection": [
      "results.id",
      "results.partiumId",
      "results.name",
      "results.createdAt",
      "results.modifiedAt"
    ],
    "matches": {
      "organization": "partium-demo-reemtsma",
      "text": "fan"
    },
    "resultOptions": {
      "limit": 5
    }
  },
}).then(res => {
  ...
});

Once you have the sessionId of an existing search, subsequent pages can be retrieved via the GET /search/state/{sessionId} endpoint. Use the limit and skip query parameters, with limit matching the resultOptions.limit value (5 in this example), and skip specifying the number of results to bypass. skip should be calculated as PAGE * LIMIT, where PAGE is the zero-based page number. To fetch the third page in this example, set skip to 2 * 5 = 10:

HTTP
Python
JavaScript

> GET https://api.partium.io/1/find/search/state/ff6d1393-7279-4045-a265-33d9b311bcaa? \
    skip=10& \
    limit=5& \
    projection=results.id,results.partiumId,results.name,results.createdAt,results.modifiedAt
> Authorization: Bearer <<Your Access Token or API Key>>
> 
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 1033
<
< {
<     "sessionId": "ff6d1393-7279-4045-a265-33d9b311bcaa",
<     "imageId": null,
<     "results": [
<         {
<             "id": "RDC27260",
<             "partiumId": "3f68855d-f157-4936-a185-3ab35b0a6652",
<             "name": "Impeller axial fan VXE V20",
<             "createdAt": "2023-06-27T15:40:11.584660Z",
<             "modifiedAt": "2024-02-16T12:23:44.641659Z"
<         },
<         {
<             "id": "RDC21212",
<             "partiumId": "79b4d3ac-669e-456c-9302-e95cdea3a7e3",
<             "name": "Fan electr. VSR 7",
<             "createdAt": "2023-06-27T15:38:33.026747Z",
<             "modifiedAt": "2024-02-16T12:16:07.472662Z"
<         },
<         {
<             "id": "RDC28082",
<             "partiumId": "431a897a-f4ad-40f6-8725-012754595757",
<             "name": "Fan 4650 N, 5 blades",
<             "createdAt": "2023-06-27T15:40:24.382543Z",
<             "modifiedAt": "2024-02-16T12:24:34.977135Z"
<         },
<         {
<             "id": "RDC28111",
<             "partiumId": "1ecc1ed1-e032-4117-a3b9-0d3d95ab7465",
<             "name": "Fan blade VEM FP80 for 4 pole motor",
<             "createdAt": "2023-06-27T15:40:24.384678Z",
<             "modifiedAt": "2024-02-16T12:24:35.985885Z"
<         },
<         {
<             "id": "RM5159929",
<             "partiumId": "04f976c5-0fb2-4f3f-b54c-80d4e42c4724",
<             "name": "Radial fan",
<             "createdAt": "2023-06-27T15:48:00.870464Z",
<             "modifiedAt": "2024-02-16T15:26:57.654846Z"
<         }
<     ],
<     "resultsTotalCount": 500
< }

response = requests.get(
  'https://api.partium.io/1/find/search/state/ff6d1393-7279-4045-a265-33d9b311bcaa?'
  'skip=10&'
  'limit=5&'
  'projection=results.id,results.partiumId,results.name,results.createdAt,results.modifiedAt',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
)

fetch('https://api.partium.io/1/find/search/state/ff6d1393-7279-4045-a265-33d9b311bcaa? \
    skip=10& \
    limit=5& \
    projection=results.id,results.partiumId,results.name,results.createdAt,results.modifiedAt', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
}).then(res => {
  ...
});

Note that both the POST /search and GET /search/state/{sessionId} endpoints include a resultsTotalCount field in their JSON responses. This field indicates the total number of results before any limit or skip parameters are applied. It allows to determine the total number of results available and calculate the number of pages required for complete retrieval.