# 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:


```json
{
  "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"
}
```


```xml
<JsonSchema
    schema={{
        type: 'object',
        description: 'A representation of a location',
        properties: {
            id: {
                type: 'uuid',
                description: 'Universally Unique Identifier to the location.',
                example: '440fffc6-3d2f-4cb2-9b98-93f0f1a87f3a'
            },
            gln: {
                type: 'string',
                description: 'Global location number of the location.',
                example: '1234567890123'
            },
            name: {
                type: 'string',
                description: 'Name of the address.',
                example: 'Simacan HQ'
            },
            geoReference: {
                type: 'object',
                description: 'Describes the geographical position of the location. Though OTM5 supports many different referencing methods only latLonPointGeoReference is supported by this API',
                properties: {
                    type: {
                        type: 'string',
                        description: 'Type of reference.',
                        example: 'latLonPointGeoReference'
                    },
                    lat: {
                        type: 'number',
                        description: 'Latitude',
                        example: 52.370216
                    },
                    lon: {
                        type: 'number',
                        description: 'longitude',
                        example: 4.895168
                    }
                }
            },
            administrativeReference: {
                type: 'object',
                description: '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',
                properties: {
                    name: {
                        type: 'string',
                        description: 'Name of the address.',
                        example: 'Main entrance'
                    },
                    street: {
                        type: 'string',
                        description: 'Street of the address.',
                        example: 'Valutaboulevard'
                    },
                    houseNumber: {
                        type: 'string',
                        description: 'House number of the address, without any extension.',
                        example: '16'
                    },
                    houseNumberAddition: {
                        type: 'string',
                        description: 'Addition or extension of the house number.',
                        example: 'A'
                    },
                    city: {
                        type: 'string',
                        description: 'The city of the address.',
                        example: 'Amersfoort'
                    },
                    country: {
                        type: 'string',
                        description: '[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha-2 country code.',
                        example: 'NL'
                    }
                }
            },
            contactDetails: {
                type: 'object',
                description: 'Contact details for this Location.',
                properties: {
                    type: {
                        type: 'string',
                        enum: ["phone", "email", "name", "firstName", "lastName"],
                        description: 'Type of detail.'
                    },
                    value: {
                        type: 'string',
                        description: 'Contact detail of the specified type.',
                    }
                }
            },
            type: {
                type: 'string',
                enum: ["warehouse", "store", "customer"],
                description: 'The type of location.',
                example: 'warehouse'
            }
        }
    }}
/>
```

### 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:


```json
{
  "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"
}
```

<JsonSchema
schema={{
type: 'object',
description: 'A representation of a location',
properties: {
id: {
type: 'uuid',
description: 'Universally Unique Identifier to the location.',
example: '440fffc6-3d2f-4cb2-9b98-93f0f1a87f3b'
},
gln: {
type: 'string',
description: 'Global location number of the location.',
example: '1234567890123'
},
name: {
type: 'string',
description: 'Name of the address.',
example: 'Simacan HQ'
},
geoReference: {
type: 'object',
description: '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',
properties: {
type: {
type: 'string',
description: 'Type of reference.',
example: 'addressGeoReference'
},
name: {
type: 'string',
description: 'Name of the address.',
example: 'Main entrance'
},
street: {
type: 'string',
description: 'Street of the address.',
example: 'Valutaboulevard'
},
houseNumber: {
type: 'string',
description: 'House number of the address, without any extension.',
example: '16'
},
houseNumberAddition: {
type: 'string',
description: 'Addition or extension of the house number.',
example: 'A'
},
city: {
type: 'string',
description: 'The city of the address.',
example: 'Amersfoort'
},
country: {
type: 'string',
description: '[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha-2 country code.',
example: 'NL'
}
}
},
contactDetails: {
type: 'object',
description: 'Contact details for this Location.',
properties: {
type: {
type: 'string',
enum: ["phone", "email", "name", "firstName", "lastName"],
description: 'Type of detail.'
},
value: {
type: 'string',
description: 'Contact detail of the specified type.',
}
}
},
type: {
type: 'string',
enum: ["warehouse", "store", "customer"],
description: 'The type of location.',
example: 'warehouse'
}
}
}}
/>

### 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:


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

<JsonSchema
schema={{
type: 'object',
description: 'A representation of a location',
properties: {
id: {
type: 'uuid',
description: 'Universally Unique Identifier to the location.',
example: '440fffc6-3d2f-4cb2-9b98-93f0f1a87f3c'
},
name: {
type: 'string',
description: 'Name of the address.',
example: 'Location on some road'
},
geoReference: {
type: 'object',
description: 'Describes the geographical position of the location. Though OTM5 supports many different referencing methods only latLonPointGeoReference is supported by this API',
properties: {
type: {
type: 'string',
description: 'Type of reference.',
example: 'latLonPointGeoReference'
},
lat: {
type: 'number',
description: 'Latitude',
example: 52.370216
},
lon: {
type: 'number',
description: 'longitude',
example: 4.895168
}
}
},
type: {
type: 'string',
enum: ["warehouse", "store", "customer"],
description: 'The type of location.',
example: '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.