Skip to content

MapTrip Storage API

The MapTrip Storage is an API designed for users of the truck route planning service MapTrip Maps. It allows to import vehicles, locations, and routes automatically into Maps and add labels for easier organization. Four sub-APIs are available for this purpose, which can be used, for example, to create, read, update, and delete routes.

For an example that reads addresses from a CSV file, geocodes them, creates locations from the geocoder results, determines the optimal order, and saves a tour, see Demo: Tour Import with Python Client.

Labels

A label consists of a name and a color. It can be added to vehicles, locations and tours and used for various purposes:

  • If you have multiple company locations, you can use a label for each one and view only the vehicles, customers, and routes for that location in Maps
  • You can tag urgent orders with a label to keep better track of them
  • When you import data automatically, you can apply a label to that data to make manual verification easier

Create Labels

To create a new label, send an instance of a Label without the read-only properties id, createdAt and modifiedAt to the endpoint [POST] /storage/label:

curl -X 'POST' \
  'https://api.maptrip.de/v1/storage/label' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "important",
  "color": "#bd1550"
}'

The endpoint returns the newly created label:

{
  "id": "d1e4b7da-2139-4168-ab00-758b59200904",
  "name": "important",
  "color": "#bd1550",
  "createdAt": "2026-07-21T07:56:44.027092754Z",
  "modifiedAt": "2026-07-21T07:56:44.027092754Z"
}

Read Labels

There are two endpoints to retrieve labels:

  • [GET] /storage/label returns all labels from your MapTrip Maps account
  • [GET] /storage/label/{id} returns the label with the provided id, or 404 Not Found if there is no label with this ID

Update Labels

You can use the endpoint [PUT] /storage/label/{id} to update a label. The parameter id specifies which label is being updated, and the body contains the new properties:

curl -X 'PUT' \
  'https://api.maptrip.de/v1/storage/label/d1e4b7da-2139-4168-ab00-758b59200904' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "very important",
  "color": "#ff0000"
}'

The response will contain the updated label, or 404 Not Found if there is no label with this ID:

{
  "id": "d1e4b7da-2139-4168-ab00-758b59200904",
  "name": "very important",
  "color": "#ff0000",
  "createdAt": "2026-07-21T07:56:44.027092754Z",
  "modifiedAt": "2026-07-22T12:50:34.454045453Z"
}

Delete Labels

The endpoint [DELETE] /storage/label/{id} deletes the label with the provided id. The response is 204 No Content if it was successfully deleted, or 404 Not Found if there is no label with this ID.

Vehicles

A vehicle describes the characteristics of a vehicle, such as its type (car or truck), weight, dimensions, whether it is transporting hazardous materials, and other details. When creating a tour, specify a vehicle so that you can obtain a route suitable for that vehicle.

Use this sub-API to create and manage your vehicles, and specify the ID of the corresponding vehicle when creating a tour.

Different Model Classes

GET requests use a slightly different model class than POST and PUT requests: When querying vehicles, you receive a Vehicle object containing all the information from the vehicle's labels, as well as the creation and modification dates of the vehicle. When creating or updating, you only need to specify the IDs of the labels in a VehicleRequest.

Create Vehicles

To create a new vehicle, send an instance of a VehicleRequest to the endpoint [POST] /storage/vehicle:

curl -X 'POST' \
  'https://api.maptrip.de/v1/storage/vehicle' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My Truck",
  "vehicleType": "truck_highway",
  "width": 2.45,
  "height": 2.7,
  "length": 13.6,
  "weight": 25000,
  "axles": 5,
  "axleLoad": 8000,
  "hazardousGoods": false,
  "explosiveMaterials": false,
  "materialsHarmfulToWater": false,
  "tunnelRestrictionCode": "A",
  "co2EmissionClass": 2,
  "emissionStandard": "Euro0"
}'

The endpoint returns the newly created vehicle:

{
  "name": "My Truck",
  "vehicleType": "truck_highway",
  "width": 2.45,
  "height": 2.7,
  "length": 13.6,
  "weight": 25000,
  "axles": 5,
  "axleLoad": 8000,
  "hazardousGoods": false,
  "explosiveMaterials": false,
  "materialsHarmfulToWater": false,
  "tunnelRestrictionCode": "A",
  "co2EmissionClass": 2,
  "emissionStandard": "Euro0",
  "id": "0962cfb5-0228-4e92-abba-64d8e7209631",
  "labels": [],
  "createdAt": "2026-07-22T13:49:43.750100726Z",
  "modifiedAt": "2026-07-22T13:49:43.750100726Z"
}

Read Vehicles

There are three endpoints to retrieve vehicles:

  • [GET] /storage/vehicle returns all vehicles from your MapTrip Maps account. This endpoint has an optional parameter label. Provide the ID of a label to filter the vehicles by this label
  • [GET] /storage/vehicle/{id} returns the vehicle with the provided id, or 404 Not Found if there is no vehicle with this ID
  • [GET] /storage/vehicle/default returns the default vehicles of MapTrip Maps

Update Vehicles

You can use the endpoint [PUT] /storage/vehicle/{id} to update a vehicle. The parameter id specifies which vehicle is being updated, and the body contains the new properties.

This example adds the previously created label:

curl -X 'PUT' \
  'https://api.maptrip.de/v1/storage/vehicle/0962cfb5-0228-4e92-abba-64d8e7209631' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My Truck",
  "vehicleType": "truck_highway",
  "width": 2.45,
  "height": 2.7,
  "length": 13.6,
  "weight": 25000,
  "axles": 5,
  "axleLoad": 8000,
  "hazardousGoods": false,
  "explosiveMaterials": false,
  "materialsHarmfulToWater": false,
  "tunnelRestrictionCode": "A",
  "co2EmissionClass": 2,
  "emissionStandard": "Euro0",
  "labels": [
    "d1e4b7da-2139-4168-ab00-758b59200904"
  ]
}'

The response will contain the updated vehicle, or 404 Not Found if there is no vehicle with this ID:

{
  "name": "My Truck",
  "vehicleType": "truck_highway",
  "width": 2.45,
  "height": 2.7,
  "length": 13.6,
  "weight": 25000,
  "axles": 5,
  "axleLoad": 8000,
  "hazardousGoods": false,
  "explosiveMaterials": false,
  "materialsHarmfulToWater": false,
  "tunnelRestrictionCode": "A",
  "co2EmissionClass": 2,
  "emissionStandard": "Euro0",
  "id": "0c2d9c1e-2125-4104-b62f-9bb5cbac98f2",
  "labels": [
    {
      "id": "d1e4b7da-2139-4168-ab00-758b59200904",
      "name": "very important",
      "color": "#ff0000",
      "createdAt": "2026-07-21T07:56:44.027092754Z",
      "modifiedAt": "2026-07-22T12:50:34.454045453Z"
    }
  ],
  "createdAt": "2026-07-22T13:49:43.750101Z",
  "modifiedAt": "2026-07-22T13:59:28.250557265Z"
}

Delete Vehicles

The endpoint [DELETE] /storage/vehicle/{id} deletes the vehicle with the provided id. The response is 204 No Content if it was successfully deleted, or 404 Not Found if there is no vehicle with this ID.

Locations

To create a tour, you have to create a location for every stop first. A location consists of a coordinate, and optionally an address, a name and labels. You can also save any information, e.g. a customer number, in the property customData.

If you don't have coordinates for your stops, you can use the Geocoder API to retrieve coordinates of addresses.

Different Model Classes

GET requests use a slightly different model class than POST and PUT requests: When querying locations, you receive a Location object containing all the information from the locations's labels, as well as the creation and modification dates of the location. When creating or updating, you only need to specify the IDs of the labels in a LocationRequest.

Create Locations

To create a new location, send an instance of a LocationRequest to the endpoint [POST] /storage/location:

curl -X 'POST' \
  'https://api.maptrip.de/v1/storage/location' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "infoware GmbH",
  "street": "Weiherstr.",
  "housenumber": "38",
  "postalcode": "53111",
  "city": "Bonn",
  "country": "DEU",
  "coordinate": {
    "lat": 50.73669,
    "lon": 7.09212
  }
}'

The endpoint returns the newly created location:

{
  "city": "Bonn",
  "postalcode": "53111",
  "zipcode": "53111",
  "street": "Weiherstr.",
  "housenumber": "38",
  "country": "DEU",
  "id": "1273ae56-9c1b-45ae-adae-746d516896a4",
  "name": "infoware GmbH",
  "coordinate": {
    "lat": 50.73669,
    "lon": 7.09212
  },
  "labels": [],
  "createdAt": "2026-07-22T15:02:07.163620306Z",
  "modifiedAt": "2026-07-22T15:02:07.163620306Z"
}

Read Locations

There are two endpoints to retrieve locations:

  • [GET] /storage/location returns all locations from your MapTrip Maps account. This endpoint has an optional parameter label. Provide the ID of a label to filter the locations by this label
  • [GET] /storage/location/{id} returns the location with the provided id, or 404 Not Found if there is no location with this ID

Update Locations

You can use the endpoint [PUT] /storage/location/{id} to update a location. The parameter id specifies which location is being updated, and the body contains the new properties.

This example adds the previously created label and a customer number in the property customData:

curl -X 'PUT' \
  'https://api.maptrip.de/v1/storage/location/1273ae56-9c1b-45ae-adae-746d516896a4' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "city": "Bonn",
  "postalcode": "53111",
  "street": "Weiherstr.",
  "housenumber": "38",
  "country": "DEU",
  "name": "infoware GmbH",
  "coordinate": {
    "lat": 50.73669,
    "lon": 7.09212
  },
  "customData": "#514",
  "labels": [
    "d1e4b7da-2139-4168-ab00-758b59200904"
  ]
}'

The response will contain the updated location, or 404 Not Found if there is no location with this ID:

{
  "city": "Bonn",
  "postalcode": "53111",
  "zipcode": "53111",
  "street": "Weiherstr.",
  "housenumber": "38",
  "country": "DEU",
  "name": "infoware GmbH",
  "coordinate": {
    "lat": 50.73669,
    "lon": 7.09212
  },
  "customData": "#514",
  "id": "1273ae56-9c1b-45ae-adae-746d516896a4",
  "labels": [
    {
      "id": "d1e4b7da-2139-4168-ab00-758b59200904",
      "name": "very important",
      "color": "#ff0000",
      "modifiedAt": "2026-07-22T12:50:34.454045Z"
    }
  ],
  "createdAt": "2026-07-22T15:02:07.163620Z",
  "modifiedAt": "2026-07-22T15:12:15.702018649Z"
}

Delete Locations

The endpoint [DELETE] /storage/location/{id} deletes the location with the provided id. The response is 204 No Content if it was successfully deleted, or 404 Not Found if there is no location with this ID.

Tours

A tour basically is a list of stops. Each stop is based on a location and may have a timeSlot or a duration (the time required to unload or visit a customer in minutes).

In addition, a tour has the following properties:

  • id (read-only): The ID of this tour
  • name: The tour will be listed with this name in MapTrip Maps
  • startTime: The start time in the local time of the zone of the tour start
  • customData: You can story any information in this property. Not used in MapTrip Maps
  • labels: A list of labels to organize your data. Can be used to filter your tours in MapTrip Maps
  • vehicle: The car or truck the tour will be calculated for
  • createdAt and modifiedAt (read-only): Dates when this tour was created or modified

Different Model Classes

GET requests use a slightly different model class than POST and PUT requests: When querying tours, you receive a Tour object containing all the information from the tour's vehicle, stops and labels, as well as the creation and modification dates of the tour. When creating or updating, you only need to specify the IDs of the vehicle, locations and labels in a TourRequest.

Create Tours

To create a new tour, send an instance of a TourRequest to the endpoint [POST] /storage/tour:

curl -X 'POST' \
  'https://api.maptrip.de/v1/storage/tour' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My Tour",
  "startTime": "18:00:00",
  "vehicle": "c2eac784-30fa-4f89-9685-0c4c8d0537fe",
  "stops": [
    {
      "address": "d4506051-c073-4c76-8309-f4d15908a2f6"
    },
    {
      "address": "c24ce8af-8892-4142-9afb-cb1997e32f41",
      "duration": 120
    },
    {
      "address": "d4506051-c073-4c76-8309-f4d15908a2f6"
    }
  ]
}'

The endpoint returns the newly created tour:

{
  "name": "My Tour",
  "startTime": "18:00:00",
  "id": "cbb09382-0dce-46f2-b83c-b3c2a9149630",
  "labels": [],
  "vehicle": {
    "name": "Car",
    "vehicleType": "Car",
    "width": 1.83,
    "height": 1.5,
    "length": 4.8,
    "weight": 1500,
    "axles": 2,
    "axleLoad": 1000,
    "hazardousGoods": false,
    "explosiveMaterials": false,
    "materialsHarmfulToWater": false,
    "id": "c2eac784-30fa-4f89-9685-0c4c8d0537fe",
    "labels": [],
    "createdAt": "2024-03-05T10:22:35.999075Z",
    "modifiedAt": "2024-03-05T10:22:35.999075Z"
  },
  "stops": [
    {
      "address": {
        "city": "Bonn",
        "part": "Nordstadt",
        "postalcode": "53111",
        "zipcode": "53111",
        "street": "Weiherstr.",
        "housenumber": "38",
        "country": "DEU",
        "name": "Home",
        "coordinate": {
          "lat": 50.73669,
          "lon": 7.09212
        },
        "id": "d4506051-c073-4c76-8309-f4d15908a2f6",
        "labels": [],
        "createdAt": "2024-09-18T11:11:51.772129Z",
        "modifiedAt": "2025-01-21T12:12:57.479347Z"
      }
    },
    {
      "address": {
        "city": "Bonn",
        "part": "Nordstadt",
        "postalcode": "53111",
        "zipcode": "53111",
        "street": "Georgstr.",
        "housenumber": "28",
        "country": "DEU",
        "name": "Strandhaus",
        "coordinate": {
          "lat": 50.74233,
          "lon": 7.09146
        },
        "id": "c24ce8af-8892-4142-9afb-cb1997e32f41",
        "labels": [
          {
            "id": "c7badbef-f8d9-4efb-80fe-00cb2a9230f6",
            "name": "imported",
            "color": "#ff0000",
            "createdAt": "2026-07-08T09:38:11.886367Z",
            "modifiedAt": "2026-07-08T09:38:11.886367Z"
          }
        ],
        "createdAt": "2026-07-14T11:29:42.304750Z",
        "modifiedAt": "2026-07-14T11:29:42.304750Z"
      },
      "duration": 120
    },
    {
      "address": {
        "city": "Bonn",
        "part": "Nordstadt",
        "postalcode": "53111",
        "zipcode": "53111",
        "street": "Weiherstr.",
        "housenumber": "38",
        "country": "DEU",
        "name": "Home",
        "coordinate": {
          "lat": 50.73669,
          "lon": 7.09212
        },
        "id": "d4506051-c073-4c76-8309-f4d15908a2f6",
        "labels": [],
        "createdAt": "2024-09-18T11:11:51.772129Z",
        "modifiedAt": "2025-01-21T12:12:57.479347Z"
      }
    }
  ],
  "createdAt": "2026-07-23T08:55:20.078232Z",
  "modifiedAt": "2026-07-23T08:55:20.078232Z"
}

Read Tours

There are two endpoints to retrieve tours:

  • [GET] /storage/tour returns all tours from your MapTrip Maps account. This endpoint has an optional parameter label. Provide the ID of a label to filter the tours by this label
  • [GET] /storage/tour/{id} returns the tour with the provided id, or 404 Not Found if there is no tour with this ID

Update Tours

You can use the endpoint [PUT] /storage/tour/{id} to update a tour. The parameter id specifies which tour is being updated, and the body contains the new properties.

This example adds the previously created label and a tour number in the property customData:

curl -X 'PUT' \
  'https://api.maptrip.de/v1/storage/tour/cbb09382-0dce-46f2-b83c-b3c2a9149630' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My Tour",
  "startTime": "18:00:00",
  "vehicle": "0962cfb5-0228-4e92-abba-64d8e7209631",
  "stops": [
    {
      "address": "a8996d47-2fea-4c69-846a-8aebb9615b08"
    },
    {
      "address": "c0f39c29-5649-4650-8fc4-145b16ada3ba",
      "duration": 120
    },
    {
      "address": "a8996d47-2fea-4c69-846a-8aebb9615b08"
    }
  ],
  "customData": "Tour #3",
  "labels": [
    "d1e4b7da-2139-4168-ab00-758b59200904""
  ]
}'

The response will contain the updated tour, or 404 Not Found if there is no tour with this ID:

{
  "name": "My Tour",
  "startTime": "18:00:00",
  "customData": "Tour #3",
  "id": "cbb09382-0dce-46f2-b83c-b3c2a9149630",
  "labels": [
    {
      "id": "d1e4b7da-2139-4168-ab00-758b59200904"",
      "name": "very important",
      "color": "#ff0000",
      "modifiedAt": "2026-07-22T12:50:34.454045Z"
    }
  ],
  "vehicle": {
    "name": "Car",
    "vehicleType": "Car",
    "width": 1.83,
    "height": 1.5,
    "length": 4.8,
    "weight": 1500,
    "axles": 2,
    "axleLoad": 1000,
    "hazardousGoods": false,
    "explosiveMaterials": false,
    "materialsHarmfulToWater": false,
    "id": "0962cfb5-0228-4e92-abba-64d8e7209631",
    "labels": [],
    "createdAt": "2024-03-05T10:22:35.999075Z",
    "modifiedAt": "2024-03-05T10:22:35.999075Z"
  },
  "stops": [
    {
      "address": {
        "city": "Bonn",
        "part": "Nordstadt",
        "postalcode": "53111",
        "zipcode": "53111",
        "street": "Weiherstr.",
        "housenumber": "38",
        "country": "DEU",
        "name": "Home",
        "coordinate": {
          "lat": 50.73669,
          "lon": 7.09212
        },
        "id": "a8996d47-2fea-4c69-846a-8aebb9615b08",
        "labels": [],
        "createdAt": "2024-09-18T11:11:51.772129Z",
        "modifiedAt": "2025-01-21T12:12:57.479347Z"
      }
    },
    {
      "address": {
        "city": "Bonn",
        "part": "Nordstadt",
        "postalcode": "53111",
        "zipcode": "53111",
        "street": "Georgstr.",
        "housenumber": "28",
        "country": "DEU",
        "name": "Strandhaus",
        "coordinate": {
          "lat": 50.74233,
          "lon": 7.09146
        },
        "id": "c0f39c29-5649-4650-8fc4-145b16ada3ba",
        "labels": [],
        "createdAt": "2026-07-14T11:29:42.304750Z",
        "modifiedAt": "2026-07-14T11:29:42.304750Z"
      },
      "duration": 120
    },
    {
      "address": {
        "city": "Bonn",
        "part": "Nordstadt",
        "postalcode": "53111",
        "zipcode": "53111",
        "street": "Weiherstr.",
        "housenumber": "38",
        "country": "DEU",
        "name": "Home",
        "coordinate": {
          "lat": 50.73669,
          "lon": 7.09212
        },
        "id": "a8996d47-2fea-4c69-846a-8aebb9615b08",
        "labels": [],
        "createdAt": "2024-09-18T11:11:51.772129Z",
        "modifiedAt": "2025-01-21T12:12:57.479347Z"
      }
    }
  ],
  "createdAt": "2026-07-23T08:55:20.078232Z",
  "modifiedAt": "2026-07-23T09:18:11.222024Z"
}

Delete Tours

The endpoint [DELETE] /storage/tour/{id} deletes the tour with the provided id. The response is 204 No Content if it was successfully deleted, or 404 Not Found if there is no tour with this ID.