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 combination 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 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. If this option is missing, sources are used as destinations.

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

Return type

map

geodata.computeRoutes(routes)
geodata.computeRoutes(routes, options)

Computes the fastest routes between pairs of coordinates. This function is useful if you want to draw the routes on a map or create applications that need to know which sections are crossed one by one.

The first argument contains a list of routes in the form of a map indexed from 0 to n-1 (where n is the number of routes). A route itself is also a map containing two fields, ‘source’ and ‘destination’, representing points (latitude, longitude). The different ways to model a point are detailed in a table below.

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

The returned value is a map containing as many values as requested routes indexed from 0 to n-1. Each route includes the requested attributes (duration and/or distance) as well as the geometry of the route returned as a map following the GeoJSON format (type LineString). GeoJSON is an open standard created to represent geographical shapes like points, lines or polygons. The latest version of the format is available on the IETF website.

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.

The geodetic system selected to represent the points is WGS84. It is used in particular by the GPS and Galileo positioning systems.

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

Matrix example

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}}}

Routes example

The following example calculates the shortest route between the city pairs Paris/Lyon, and New-York/Seattle:

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

...

routes = {
    // Paris/Lyon
    {
        source: { latitude: 48.8589384, longitude: 2.2646345 },
        destination: { latitude: 45.7580409, longitude: 4.7527295 }
    },
    // New-york/Seattle
    // Note that this route uses the alternative, shorter representation
    // for the points. The behavior remains the same, however.
    {
        source: { 40.69754, -74.3093251 },
        destination: { 47.6131419, -122.5068716 }
    }
};

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

result = geodata.computeRoutes(routes, options);
routeParisLyon = result[0];
routeNewYorkSeattle = result[1];

println("GeoJSON LineString between Paris and Lyon: ", routeParisLyon.geometry);
println("Travel time between Paris and Lyon: ", round(routeParisLyon.duration / 3600), "h");
println("Distance between New-York and Seattle: ", round(routeNewYorkSeattle.distance / 1000), "km");

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).