Creating or updating locations using OTM5

Locations that are referenced from planning files can be supplied either as a part of a trip planning or separately and then referenced from the planning. This document describes how to upload them separately.

Endpoint

PUT https://planning-receive-api.services.simacan.com/otm/api/v5/locations
Content-Type: application/json

A look at the basic format

We are going to take you through the data structure, step by step. Note that this is about inserting or updating locations. Locations can be created with or without GPS coordinate and the structure of these messages differ.

Location with coordinate

Let's take a look at an example of a location with a coordinate:

Copy

Copied

{
  "id": "440fffc6-3d2f-4cb2-9b98-93f0f1a87f3a",
  "geoReference": {
    "lat": 52.370216,
    "lon": 4.895168,
    "type": "latLonPointGeoReference"
  },
  "administrativeReference": {
    "name": "Simacan",
    "street": "Valutaboulevard",
    "houseNumber": "16",
    "postalCode": "1234AB",
    "city": "Amersfoort"
  },
  "contactDetails": [
    {
      "value": "Simacan",
      "type": "name"
    },
    {
      "value": "0612345678",
      "type": "phone"
    },
    {
      "value": "sim@can.com",
      "type": "email"
    }
  ],
  "type": "warehouse"
}

id	uuid Universally Unique Identifier to the location.
gln	string Global location number of the location.
name	string Name of the address.
	object Describes the geographical position of the location. Though OTM5 supports many different referencing methods only latLonPointGeoReference is supported by this API
	object Address information that is used as an administrative reference. For example: when the actual load location is different from the officially registered location, this holds the latter
	object Contact details for this Location.
type	string The type of location. Enum: "warehouse" "store" "customer"

Location without coordinate

It is possible to supply a location without a GPS coordinate and only address information. We will attempt to infer the coordinate from the address information in this case (which might fail). If the coordinate cannot be determined the coordinate can be manually set from the masterdata application.

Let's take a look at an example of a location with a coordinate:

Copy

Copied

{
  "id": "440fffc6-3d2f-4cb2-9b98-93f0f1a87f3b",
  "geoReference": {
    "type": "addressGeoReference"
    "name": "Simacan",
    "street": "Valutaboulevard",
    "houseNumber": "16",
    "postalCode": "1234AB",
    "city": "Amersfoort"
  },
  "contactDetails": [
    {
      "value": "Simacan",
      "type": "name"
    },
    {
      "value": "0612345678",
      "type": "phone"
    },
    {
      "value": "sim@can.com",
      "type": "email"
    }
  ],
  "type": "warehouse"
}

id	uuid Universally Unique Identifier to the location.
gln	string Global location number of the location.
name	string Name of the address.
	object Address information that is used as an administrative reference. For example: when the actual load location is different from the officially registered location, this holds the latter
	object Contact details for this Location.
type	string The type of location. Enum: "warehouse" "store" "customer"

Location without address information

It is possible to supply a location with just a GPS coordinate and no address information.

Let's take a look at an example of a location with only a coordinate:

Copy

Copied

{
  "id": "440fffc6-3d2f-4cb2-9b98-93f0f1a87f3c",
  "geoReference": {
    "lat": 52.370216,
    "lon": 4.895168,
    "type": "latLonPointGeoReference"
  },
  "name": "Location on some road",
  "type": "customer"
}

id	uuid Universally Unique Identifier to the location.
name	string Name of the address.
	object Describes the geographical position of the location. Though OTM5 supports many different referencing methods only latLonPointGeoReference is supported by this API
type	string The type of location. Enum: "warehouse" "store" "customer"

Updating your locations

Now that you have seen the appropriate format, you should also be aware that it is possible to update locations that you sent to us before. Location are matched by their Location ID. If the location ID exists the fields of that location will be updated. If it does not exist, a new location will be created.