Skip to content
/
Managing Locations
Last updated

Managing Locations

Overview

Locations are fundamental to transport management. They represent warehouses, offices, delivery addresses, and any other geographic point or area in your operations. Accurate location data ensures correct route calculations, geofencing, and delivery tracking.

Creating a Location

Create a location from an address. Transportial will geocode the address to determine coordinates:

curl -X POST https://api.otms.transportial.com/api/location \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Amsterdam Warehouse",
    "administrativeReference": {
      "name": "Amsterdam Warehouse",
      "street": "Havenstraat",
      "houseNumber": "12",
      "postalCode": "1013 AK",
      "city": "Amsterdam",
      "country": "NL"
    }
  }'

Response:

{
  "success": true,
  "message": "OK",
  "location": {
    "id": "location-uuid",
    "name": "Amsterdam Warehouse",
    "administrativeReference": {
      "street": "Havenstraat",
      "houseNumber": "12",
      "postalCode": "1013 AK",
      "city": "Amsterdam",
      "country": "NL"
    },
    "geoReference": {
      "lat": 52.3811,
      "lng": 4.8796
    },
    "createdAt": "2026-03-22T10:00:00Z"
  }
}

Setting Custom Coordinates

If you need precise coordinates (e.g., a specific loading dock), provide them directly:

curl -X POST https://api.otms.transportial.com/api/location \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Loading Dock B",
    "administrativeReference": {
      "street": "Havenstraat",
      "houseNumber": "12",
      "postalCode": "1013 AK",
      "city": "Amsterdam",
      "country": "NL"
    },
    "geoReference": {
      "lat": 52.38125,
      "lng": 4.87980
    }
  }'

Checking for Duplicates

Before creating a location, check if it already exists in your system:

curl -X POST https://api.otms.transportial.com/api/location/duplicates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Amsterdam Warehouse",
    "administrativeReference": {
      "street": "Havenstraat",
      "houseNumber": "12",
      "postalCode": "1013 AK",
      "city": "Amsterdam",
      "country": "NL"
    }
  }'

The response will list any existing locations that match or closely match your input, allowing you to reuse existing records instead of creating duplicates.

Updating a Location

Update specific fields on an existing location. Only the fields you provide will be changed:

curl -X POST https://api.otms.transportial.com/api/location \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "location-uuid",
    "name": "Amsterdam Main Warehouse"
  }'

Linking Locations to Businesses

Locations can be linked to businesses during business creation or update. This associates warehouses, offices, and other facilities with the companies that operate them:

curl -X POST https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Acme Logistics B.V.",
    "locations": [
      { "id": "location-uuid" }
    ]
  }'

Using Locations in Transport Orders

Locations are referenced throughout the transport flow — in actions (where to load/unload), in businesses (company addresses), and in events (arrival/departure points):

curl -X POST https://api.otms.transportial.com/api/trip:route \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Warehouse delivery",
    "type": "road",
    "actions": [
      {
        "type": "load",
        "location": { "id": "pickup-location-uuid" },
        "startTime": "2026-03-23T08:00:00Z"
      },
      {
        "type": "move"
      },
      {
        "type": "unload",
        "location": { "id": "delivery-location-uuid" },
        "startTime": "2026-03-23T11:00:00Z"
      }
    ]
  }'

Next Steps

Previous page
Next page