Custom Data Upload

The Localion Navigator provides a HTTP-API which allows customers to upload their own custom data which will be deployed to the customers users of the Localion Navigator.

Uploading Customer Data

To upload customer data through the API, you must use the /upload endpoint. The upload is in the form of a ZIP archive that contains the files to be updated at the top level. Even if only one file should be updated, you must upload that file in a ZIP archive.

Metadata

When requesting to upload customer data, you must also provide metadata. The following metadata must be provided:

x-ln-email: The email address which will receive the final result of the update request. Example: max.mustermann@beispiel.com
x-ln-files: A comma-separated list of file names that are part of the update. Example: example_categories.lpc,example_pois.lpd
x-ln-update-type: Specifies which type of update to perform. It must be either "minor" or "major". Example: minor

Authentication

For each request to the API, you must include an API key as Authorization header. If you have not received an API-Key yet, please contact the support at navigation@localion.de

Naming of data files

The names of all files in the ZIP archive must comply with the following rules:

Each filename consists of the files identifier, the separator _, the version number and the file extension - e.g. company_offices_pois_22104.lpd. In the example company_offices_pois is the identifier, 22104 the version number and lpd the file extension
It is allowed to use any number of _ in the identifier, but no further _ may follow after the version number
File identifiers should not be changed, once the first version of those files has been distributed. Doing so may lead to changes of how it is displayed to users of the Localion Navigator
The version number must consist of 5 digits and may not be decremented compared to previously distributed versions of the data
The last two digits of the version number determine the minor version and the leading digits determine the major version. As the minor version cannot be increased beyond 99, a major update must be done if the minor version has reached 99 and the data should be updated again.
For major updates the files identifiers must be unique
For minor updates, the major version must not be incremented
The file extension should be one of: lpd, lpc, db or xmd

Update types

The API supports two types of updates: major and minor.

Major update

A major update requires uploading all files to be made available to the client's users. After a successful major update, the users of the Localion Navigator will receive an update that contains exactly the uploaded data. Old data that is not included, and should therefore no longer to be distributed, will be removed from the users' devices. When the navigator is reinstalled after a major update, the user will only receive the data of that major update.

Warning

A major update MUST contain all files that Localion Navigator users should receive. Not included files will no longer be distributed and be removed from users devices.

All files must also have a new filename, so at least the version must be updated.

This is the case even if a files contents have not changed.

It is however not required that the major version be updated.

Example:

Data provided to date:

company_offices_pois_22103.lpd
company_offices_poi_categories_22101.lpc
customer_buildings_pois_22101.lpd
customer_buildings_poi_categories_22101.lpc

Data in update:

company_offices_pois_23101.lpd
company_offices_poi_categories_22102.lpc
address_points_pois_23100.lpd
address_points_poi_categories_22102.lpc

Data offered for download at user after new installation:

company_offices_pois_23101.lpd
company_offices_poi_categories_22102.lpc
address_points_pois_23100.lpd // new files were added, missing files were removed
address_points_poi_categories_23100.lpc // new files were added, missing files were removed

Minor update

Only the files that should be updated must be uploaded for a minor update. These files must be a minor update for the files that have already been distributed. A minor update is any update that increments only the last two digits in a files version. New files cannot be distributed with a minor update. After a successful minor update, users of the Localion Navigator will receive an update containing only the new files. When the navigator is reinstalled, the new files will be offered along with the files that were not updated.

Example:

Data provided so far:

company_offices_pois_22103.lpd
company_offices_poi_categories_22101.lpc
customer_buildings_pois_22101.lpd
customer_buildings_poi_categories_22101.lpc

Data in update:

company_offices_pois_22104.lpd
customer_buildings_pois_22102.lpd

Data offered for download at user after new installation:

company_offices_pois_22104.lpd
company_offices_poi_categories_22101.lpc
customer_buildings_pois_22102.lpd
customer_buildings_poi_categories_22101.lpc

Uploading larger updates

For updates larger than 10 MB, the upload must be done in two steps:

Make a request to the /generateLargeUploadUrl endpoint to generate a temporary upload URL. Pass the metadata in this request.
Use the generated URL to upload the actual file as binary data using the PUT method.

URL and endpoints

This API is accessible through the URL: https://customerapi.navigator.localion.de/customerData. The following endpoints are provided:

/upload (PUT)
/generateLargeUploadUrl (GET)

/upload

This endpoint allows the direct upload of new data in the form of a ZIP archive with a maximum size of 10 MB. Specify the metadata in the header and the ZIP archive as binary data in the body. The response has status code 200 on successful upload.

Required header params:

Authorization: The API-Key, that you received from LOGIBALL
- Example: A12BC3DE4F56GHIJ
x-ln-email: The email address which will receive the final result of the update request.
- Example: max.mustermann@beispiel.com
x-ln-files: A comma-separated list of file names that are part of the update.
- Example: example_categories.lpc,example_pois.lpd
x-ln-update-type: Specifies which type of update to perform. It must be either "minor" or "major".
- Example: minor
Content-Type: Standard HTTP header, which must always be application/zip

Required body:

The ZIP archive as binary data

The response has status code 200 if the upload was successful.

Different status codes mean an error and contain a more detailed description in the body.

minor_update

Example Request:

curl --location --request PUT 'https://customerapi.navigator.localion.de/customerData/upload' \
--header 'Authorization: A12BC3DE4F56GHIJ' \
--header 'x-ln-email: max.musterman@example.com' \
--header 'x-ln-update-type: minor' \
--header 'x-ln-files: example_categories.lpc,example_pois.lpd' \
--header 'Content-Type: application/zip' \
--data '@/Users/max.musterman/Downloads/someData/Archiv.zip'

/generateLargeUploadUrl

This endpoint generates a temporary upload URL for large data with a file size over 10 MB. Specify the metadata in the header. The response contains the generated URL in the body and has status code 200 on successful generation.

Required header params:

Authorization: The API-Key, that you received from LOGIBALL
- Example: A12BC3DE4F56GHIJ
x-ln-email: The email address which will receive the final result of the update request.
- Example: max.mustermann@beispiel.com
x-ln-files: A comma-separated list of file names that are part of the update.
- Example: example_categories.lpc,example_pois.lpd
x-ln-update-type: Specifies which type of update to perform. It must be either "minor" or "major".
- Example: minor

The response has the status code 200 and contains the generated url in the body if the generation was successful. This URL must then be called with the ZIP file containing the updated files as binary data in the body and the HTTP-method PUT.

Further details can be found in the Open API Documentation

Different status codes mean an error and contain a more detailed description in the body.

major_update

Example Requests:

curl --location --request PUT 'https://customerapi.navigator.localion.de/customerData/generateLargeUploadUrl' \
--header 'Authorization: A12BC3DE4F56GHIJ' \
--header 'x-ln-email: max.mustermann@beispiel.com' \
--header 'x-ln-update-type: major' \
--header 'x-ln-files: example_categories.lpc,example_pois.lpd' \
--data '@/Users/max.musterman/Downloads/someData/Archiv.zip'

curl --location --request PUT 'https://s3.eu-central-1.amazonaws.com/uploadapi.navigator.localion.de/ed8f23c7-03e6-4c4a-8adb-775a6a262e22/data.zip?some=parameter' \
--header 'Content-Type: application/zip' \
--data '@/Users/lmax.musterman/Downloads/BackendExampleData.zip'