This page is for an old version of Hexaly Optimizer. We recommend that you update your version and read the documentation for the latest stable release.

Geodata module

This module offers various functions to calculate shortest paths, distance matrices and extract geographic data, anywhere in the world with very short response times. The data used for the calculations are based on OpenStreetMap <https://www.openstreetmap.org/copyright>.

Please note that this module requires an internet connection to function properly. The geographical data sources being particularly voluminous, the treatments and the calculations are carried out on the LocalSolver servers. More technical details about the communication between LocalSolver and its servers are available at the bottom of the page.

Note

To use the features of this module, you have to put a special import statement at the begining of your LSP file: use geodata;

Module functions

geodata.computeMatrix(sources)
geodata.computeMatrix(sources, destinations)
geodata.computeMatrix(sources, destinations, options)

Computes a distance/duration matrix for a given list of geographical points.

The first argument sources represents the origin points of the computed matrix. The second argument destinations is optionnal. If it is missing, a square matrix is computed with the sources as destinations. If it is present, it is used as the destination points in the matrix. A point is the combinaison of a latitude and a longitude expressed in degrees. The different ways to model a point are detailed in a table below.

The third argument options can be used to customize the behavior of the calculations. The supported options are detailed at in a dedicated section.

The returned value is a map with at most 2 fields. If durations are asked in the options, then a field durations is present. In this field, there is a map of map with the first index being the index of the source and the second index being the index of the destination. The duration values are given in seconds. If distances are asked in the input options, then a field distances is present. it is also a map of map with the same indexing pattern as the durations field. The distance values are given in meters.

The size of the matrix computed can be up to 10000x10000. To compute a 1000x1000 matrix, the server should respond in a few seconds. Computing a 5000x5000 matrix will take less than 1 minute.

Parameters
  • sources (map) – Points to use as origin points

  • destinations (map) – Points to use as destinations. Optional is this option is missing, sources are used as destinations.

  • options (map) – Optional parameters to customize the behavior of the calculation engine.

Return type

map

Points summary

Points can be model in two ways:

  1. With a simple map with 2 elements at the index 0 and 1. The first element (at index 0) is the latitude and the second one (at index 1) is the longitude.

  2. With a map containing two or three fields described as below:

Option name

Mandatory

Default value

Description

latitude

false

Latitude of the point in degrees. Latitude must be between -90 and 90.

longitude

false

Longitude of the point in degrees. Longitude must be between -180 and 180.

keepSideOfStreet

false

Forces the engine to start the travel on the same side of the street as the point.

Options summary

Option name

Default value

Description

attributes

{‘duration’, ‘distance’}

The list of attributes in the returned matrix.

travelMode

‘car’

The travel mode used in the matrix computation. Currently, only the mode ‘car’ is available.

dataSource

‘OSM’

The data source used to generate the matrix. Currently, only the data source ‘OSM’ is available.

Examples

In the following example, a 2x2 matrix is computed. We want to use the same points as sources and destinations, so we specify the same map as sources and destinations in the arguments. We use the options to specify that we want only the duration matrix:

// Don't forget to import the geodata module at the beginning of your file
use geodata;

...

points = {
    { latitude: 40.7306, longitude: -73.9352 },
    { latitude: 34.0522, longitude: -118.2436 }
};

// You can also use this alternative representation for points
// points = {{ 40.7306, -73.9352 }, { 34.0522, -118.2436 }};

options = {
    attributes: { "duration" }
};

matrix = geodata.computeMatrix(points, points, options);
println(matrix);

The display of the matrix shows the following map:

{durations : {{0, 178912.9}, {179180.8, 0}}}

Technical requirements

Since the data is several hundred GB in size, the calculations are performed on LocalSolver servers replicated in several locations around the world. The communication between the geodata module and the LocalSolver servers are entirely done in https (tls 1.3). To work properly, make sure you have an internet connection and that no firewall is blocking outgoing traffic to the URL https://routing.localsolver.com (TCP port 443).

Note

If you need to configure a firewall to allow outbound traffic to our routing servers, make sure you do not use hardcoded IP addresses. Use DNS resolution instead, since our IP addresses can change at any-time.

In the studio

This module can be used in LocalSolver studio. In that case the https connections to the routing servers are initiated by the web browser, and are subject to the same rules as any connection initiated by the user in a browser tab (notably proxy configuration, possible filtering/blocking addon).