Geodata module¶

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:

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

Options summary¶

Examples¶

// 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);

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

// 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 Hexaly servers replicated in several locations around the world. The communication between the geodata module and the Hexaly 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).