Zum Inhalt

Deep Links

You can use Android App Links (since Version 2.4) and iOS Universal Links (since Version 2.0) to provide a destination to the Localion Navigator.

The following attributes can be used to specify the destination and the app behaviour.

Version 1: one destination

Parameter BaseType optional Example Default Description
version int yes 1 most recent version Based on the version, it can be differentiated whether an installed navigator can already process the universal link of this version. Thus it is possible to extend this link type in the future and remain clearly compatible.
ll comma separated floating point pair no 51.55548, 7.20700 - The coordinate used to calculate a route when the user starts a route calculation to this destination.
dll comma separated floating point pair yes 51.55656,7.20838 value of ll The coordinate used to calculate a route when the user starts a route calculation to this destination.
title string yes LOGIBALL nil The destination title to display in the panel above the map.
description string yes Westring%20303 nil The destination description to display in the panel above the map.
action enum yes route nil The action to perform on this destination. Available actions are: display, route, navigation and demoNavigation
specialRights string yes 1 nil Parameter to compute a route with special rights. Ignored for display.

Deep Link Example: QRCode 

https://navigator.localion.de/destination/?version=1&ll=51.55548,7.20700&dll=51.55656,7.20838&title=Logiball&description=Westring%20303,%2044629%20Herne&action=display&specialRights=1

Warning

All values must be url encoded strings. Spaces and other special characters must be encoded.

Version 2: several destinations (job)

Since app version 3.1.0 the destination link exists in a second version that can carry more than one destination.

A version 2 link uses the same path as version 1 and only three query parameters:

Parameter BaseType optional Example Default Description
version int no 2 1 Must be 2 (or higher) so the navigator reads the data parameter. A navigator that does not know this version ignores the link.
action enum yes route display The action to perform. Available actions are: display, route, navigation and demoNavigation
data string no TY6xCsIwGIRfJfxzKGmbpGk3RVA… - The destinations and their options as an encoded JSON payload, see below.

The data payload

The value of data is a JSON object that is compressed with raw deflate (RFC 1951, i.e. without a zlib or gzip header) and then encoded as base64url (RFC 4648 §5, padding may be omitted). Base64url needs no additional url encoding inside a query parameter.

{
  "stations": [
    { "ll": "51.55548,7.20700", "dll": "51.55656,7.20838", "t": "LOGIBALL", "d": "Westring 303, 44629 Herne" },
    { "ll": "51.51494,7.46605", "t": "Dortmund U" }
  ],
  "specialRights": true
}
Field BaseType optional Example Default Description
stations array no see above - The destinations in the order in which they should be driven. At least one entry is required.
stations[].ll comma separated floating point pair no 51.55548,7.20700 - The coordinate used to calculate the route to this station.
stations[].dll comma separated floating point pair yes 51.55656,7.20838 value of ll The coordinate at which the station is displayed on the map.
stations[].t string yes LOGIBALL nil The station title to display.
stations[].d string yes Westring 303, 44629 Herne nil The station description to display.
specialRights bool yes true false Whether the route may be calculated with special rights. Ignored for display.

Note

A station whose ll cannot be read is skipped, the remaining stations are still used. If no station can be read, the whole link is ignored.

Behaviour

  • One station: the link behaves exactly like a version 1 destination link, including the display action.
  • Several stations: the navigator shows the stations as a temporary job. The temporary job is read only and is not added to the user's jobs list. Depending on the action the navigator additionally
    • display: only shows the job,
    • route: calculates the route from the current position over all stations,
    • navigation: calculates the route and starts the navigation,
    • demoNavigation: calculates the route and starts a demo drive.

Example

The payload of the example above, deflated and base64url encoded, results in the following link:

https://navigator.localion.de/destination/?version=2&action=route&data=TY6xCsIwGIRfJfxzKGmbpGk3RVAhIAjiIA7FhhqIqSR_p5J3N4qg49133N0CEXu0k4_QXRZwDjoQZSGE4Io2RcUaxoDC8ANSyA9QtcoAs60P2_16pfU7l-XZRAzWj6RmNSWcy6olOxO8gUT_Fkre8lzEpWTiW7SZAj5mP5ATpCuF-DQ327ujHe-Y72GYTXoB

Creating the payload in Java/Kotlin (Android) and in Swift (iOS):

val deflater = Deflater(Deflater.BEST_COMPRESSION, true) // true = raw deflate, no zlib header
deflater.setInput(json.toByteArray())
deflater.finish()
val buffer = ByteArray(json.length + 64)
val length = deflater.deflate(buffer)
deflater.end()
val data = Base64.getUrlEncoder().withoutPadding().encodeToString(buffer.copyOf(length))

let deflated = try (json.data(using: .utf8)! as NSData).compressed(using: .zlib) // .zlib = raw deflate
let data = deflated.base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")

Warning

The data parameter must not be percent encoded again. Only characters of the base64url alphabet (A-Z, a-z, 0-9, -, _) occur in it.

iOS: default navigation app

Since app version 3.2.0 users in the EU (iOS 18.4 and later) and in Japan (iOS 26.2 and later) can choose the Localion Navigator as default navigation app in Settings → Apps → Default Apps → Navigation. iOS then hands places and directions to it as geo-navigation URLs. Such a URL is not specific to the Localion Navigator, it opens whichever app the user chose.

Action Parameter Behaviour
place coordinate, address Shows the place. A coordinate is preferred over an address; an address given next to a coordinate becomes the title. While CarPlay is connected the route to the place is calculated instead, as CarPlay shows a destination only as route preview.
directions destination, source, waypoint Calculates the route to the destination, the user starts the navigation. With a source or a waypoint (repeatable) the stations become a temporary job that is routed from the source or, without one, from the current position.

A coordinate is a comma separated floating point pair (latitude, longitude). destination, source and waypoint take such a pair, an address or a place name. Text is first looked up with the address search in all countries: online with the geocoding and, without connection or if it finds nothing, offline in every country with an installed map. Of the addresses found, the one that contains the most words of the text is taken. The POI search runs at the same time; an address that contains all words of the text wins without waiting for it, otherwise of the address and the first POI the one that contains more words of the text wins, the address on a tie. Words of up to two letters like "CA" do not count, an address also contains its country, and "Straße" matches "Str.". While text is looked up for longer than half a second, the map shows it together with a progress indicator, and CarPlay as a notice that can cancel the search. A source or waypoint that cannot be found is left out; if the place or the destination cannot be found, the navigator says so.

geo-navigation:///directions?waypoint=51.51494,7.46605&destination=Westring%20303,%2044629%20Herne

For further and more advanced app-to-app communication with the Localion Navigator refer to the intent interfaces.