List Shipment Filter Values

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/logistics/requests/unique-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/logistics/requests/unique-values"

headers = {"x-organization-id": "<x-organization-id>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "field": "<string>",
  "total_count": 123,
  "values": {
    "value": "<string>",
    "label": {},
    "count": 123
  }
}

GET

logistics

requests

unique-values

List Shipment Filter Values

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/logistics/requests/unique-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/logistics/requests/unique-values"

headers = {"x-organization-id": "<x-organization-id>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "field": "<string>",
  "total_count": 123,
  "values": {
    "value": "<string>",
    "label": {},
    "count": 123
  }
}

← Logistics API Get the distinct values a field takes across your organization’s logistics requests (shipments), each with the number of shipments using it. Call it before rendering a filter so the dropdown offers only values that exist: the vehicle types your shipments actually use, the files they came from, the people who uploaded them.

field is free text, not a closed list — and an unsupported value does not return 422. It returns an empty array:

{ "field": "toc", "total_count": 0, "values": [] }

That makes “there are no shipments” and “I misspelled the field” look identical. The three accepted values are file_id, uploaded_by and vehicle_type; check your spelling against them before concluding the organization has no data.

Only active shipments are counted. Shipments in any other status (such as error) are excluded from these values. A filter built from this response therefore matches what List Logistics Requests returns by default (trip_status unset).

Request

Headers

string

required

UUID of the organization whose shipments you are filtering.Format: UUID

string

Your API key.

Query Parameters

string

required

The field to list values for. Three values are supported:

vehicle_type — value and label are both the TOC name, <vehicle>_<type> (e.g. van_3.5_t_diesel). It is the exact string the vehicle_type[] and filter_by=vehicle_type:in[...] filters of List Logistics Requests take. Shipments without a TOC are excluded. Sorted by name.
file_id — value is the id of the source file, label is the file name. Shipments created one by one or through the API have no file: they come back as one bucket whose value is the all-zero UUID 00000000-0000-0000-0000-000000000000.
uploaded_by — value is the id of the user who uploaded the shipments, label is that user’s first and last name. Shipments with no uploader are excluded.

Anything else returns an empty array rather than an error — see the warning above.

string

Only used with field=vehicle_type: narrows the list to the TOCs of the shipments linked to this project. Ignored for file_id and uploaded_by. A project with no shipments returns an empty list, not an error.Format: UUID

Response

string

The field that was queried, echoed back verbatim — including when it is not a supported one.

integer

How many distinct values were found.

array[object]

The distinct values, each with its shipment count.

Show Value Object

string

The raw value to send back as a filter: a TOC name, a file id (or the all-zero UUID for shipments with no file), or a user id.

string | null

Human-readable caption. For vehicle_type it repeats value, untranslated. For file_id it is null on the no-file bucket. For uploaded_by it is null when the user has no name or no longer resolves to a user.

integer

Number of active shipments carrying this value. An estimate for large organizations — see below.

Large organizations

When an organization has more than 250,000 active shipments, grouping every row would take minutes, so the values come from smaller sources and the counts become approximations:

count is a PostgreSQL planner estimate, not an exact count. Use it to rank options, not to report totals.
file_id lists the organization’s file uploads that were not deleted, newest first, and count is the number of rows the file had when it was uploaded: shipments deleted later are not subtracted. The no-file bucket is added at the end when the estimate finds any.
uploaded_by lists every member of the organization, sorted by name. Members who never uploaded a shipment can appear: filtering by them returns no rows.
vehicle_type lists the TOCs the organization’s active shipments use, with estimated counts. With project_id, the threshold applies to the shipments linked to the project: a project above 250,000 gets the organization’s TOCs, a superset of the project’s. It never offers a TOC the organization does not use.

Below the threshold every value and count is exact.

Example

curl -X GET "https://api.dcycle.io/v1/logistics/requests/unique-values?field=vehicle_type&project_id=YOUR_PROJECT_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

import requests

HEADERS = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORGANIZATION_ID",
}

ACCEPTED = {"file_id", "uploaded_by", "vehicle_type"}


def shipment_filter_values(field, project_id=None):
    # The API will not tell you the field is wrong, so check it yourself
    if field not in ACCEPTED:
        raise ValueError(f"{field!r} is not one of {sorted(ACCEPTED)}")

    params = {"field": field}
    if project_id:
        params["project_id"] = project_id

    return requests.get(
        "https://api.dcycle.io/v1/logistics/requests/unique-values",
        headers=HEADERS,
        params=params,
        timeout=30,
    ).json()


data = shipment_filter_values("vehicle_type", project_id="YOUR_PROJECT_ID")
for item in data["values"]:
    print(f"{item['label']}: {item['count']}")

const ACCEPTED = ["file_id", "uploaded_by", "vehicle_type"];

async function shipmentFilterValues(field, projectId) {
  if (!ACCEPTED.includes(field)) {
    throw new Error(`${field} is not one of ${ACCEPTED.join(", ")}`);
  }

  const params = new URLSearchParams({ field });
  if (projectId) params.set("project_id", projectId);

  const response = await fetch(
    `https://api.dcycle.io/v1/logistics/requests/unique-values?${params}`,
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID",
      },
    },
  );
  return response.json();
}

Successful Response

Returns 200 OK.

{
  "field": "vehicle_type",
  "total_count": 3,
  "values": [
    {
      "value": "artic_truck_up_to_40_t_gvw_average_diesel",
      "label": "artic_truck_up_to_40_t_gvw_average_diesel",
      "count": 18240
    },
    {
      "value": "rigid_truck_7.5_12_t_gvw_average_diesel",
      "label": "rigid_truck_7.5_12_t_gvw_average_diesel",
      "count": 5312
    },
    {
      "value": "van_3.5_t_diesel",
      "label": "van_3.5_t_diesel",
      "count": 977
    }
  ]
}

A TOC name can cover several TOCs (one per region); their shipments are added into a single entry, because the filters take the name.

Common Errors

422 Unprocessable Entity

Cause: field is missing entirely, or project_id is not a valid UUID. A present but unsupported field does not fail: it succeeds with an empty array.

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "field"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Use Cases

Offer only the vehicle types a list uses

The TOC catalogue has hundreds of entries, and an organization’s shipments use a handful. Populate the vehicle type dropdown from field=vehicle_type (with the project_id of the list you are showing, if any) so every option returns rows, then send the chosen names back to List Logistics Requests:

curl -G "https://api.dcycle.io/v1/logistics/requests" \
  --data-urlencode "vehicle_type[]=van_3.5_t_diesel" \
  --data-urlencode "vehicle_type[]=rigid_truck_7.5_12_t_gvw_average_diesel" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

Find the shipments created without a file

The file_id bucket with the all-zero UUID counts the shipments created one by one or through the API. To list them, pass that value in a column filter, which reads it as “no file”: filter_by=file_id:in["00000000-0000-0000-0000-000000000000"]. The file_id[] parameter compares it literally and matches nothing.

List Logistics Requests

The shipments these values filter

Bulk Delete Requests by Filters

Apply the filter you just built to a bulk delete

List Available Vehicle Types

The full TOC catalogue, used or not

Logistics API

Everything the Logistics API covers

​Request

​Headers

​Query Parameters

​Response

​Large organizations

​Example

​Successful Response

​Common Errors

​422 Unprocessable Entity

​Use Cases

​Offer only the vehicle types a list uses

​Find the shipments created without a file

​Related Endpoints

List Logistics Requests

Bulk Delete Requests by Filters

List Available Vehicle Types

Logistics API

Request

Headers

Query Parameters

Response

Large organizations

Example

Successful Response

Common Errors

422 Unprocessable Entity

Use Cases

Offer only the vehicle types a list uses

Find the shipments created without a file

Related Endpoints