# 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. The geometry can be returned as a GeoJSON object (type LineString) or a polyline. 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. Polylines represent a sequence of compressed coordinates, encoded in base64 and returned as strings. The format was originally developed by Google. The specifications are available on the Google Maps Platform 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.

geometryType

‘geojson’

Format of results returned by `computeRoutes`. Two formats are actually supported:

• ‘geojson’: Point coordinates (latitude, longitude) are returned as arrays (maps in LSP) and follow the GeoJSON format.

• ‘polyline’: Polylines represent a sequence of compressed coordinates, encoded in base64 and returned as strings.

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