Routing API v2

Description

Computes a single routing request.

You may use this API for free if you do not exceed the amount of free requests per day. In case you want to perform more requests, upgrade to the PRO version and you will get free requests every day and then for every extra request after exceeding the free quota you will pay a fixed price per extra request. More information can be found in the pricing section.

HTTP Verb

POST

URL

https://front-remora.greatcircle.be/routings/

Request description

Content-Type

application/json

Body

The body of the POST request should be a JSON string respecting the following pattern

{
  "id": <uid>,
  "name": <string>,
  "description": <string>,
  "user": {
    "email": <string>
  },
  "param": {
    "startDate": <string w3c_datetime>,
    "route": {
      "id": <uid>,
      "name": <string>,
      "waypoints": [
        {
          "id": <uid>,
          "name": <string>,
          "type": "Point",
          "coordinates": [ <number longitude>, <number latitude> ]
        }...(2;*)
      ],
      "exclusionAreas": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Polygon",
              "coordinates": [ [ [ <number longitude>, <number latitude> ]... ]... ]
            },
            "properties": {
              "id": <uid>,
              "name": <string>
            }
          }...
        ]
      }
    },
    "sailboat": {
      "id": <uid>,
      "name": <string>,
      "polars": [
        {
          "id": <uid>,
          "name": <string>,
          "index": <string index_mode>,
          "windAngles": [ <number degrees>... ],
          "windSpeeds": [ <number knots>... ],
          "sails": [ <string>... ],
          "values": [ [ <number knots>... ]... ]
        }...
      ],
      "maxSpeed": <number knots>
    },
    "weather": {
      "weatherModelNames": [ <string weather_model>... ],
      "variables": [ <string weather_variable>... ],
      "windFactor": <number proportion>,
      "waveFactor": <number proportion>,
      "waveFactorMax": <number proportion>,
      "maxWindSpeed": <number knots>,
      "maxWaveHeight": <number meters>
    },
    "method": {
      "methodName": "isochrone",
      "precision": 0,
      "dt": 3600,
      "headingInc": 1,
      "sectorWidth": 10
    },
    "performance": {
      "tackPenalty": <number seconds>,
      "polarFactors": {
        "day": <number proportion>,
        "night": <number proportion>
      },
      "minTwa": <number knots>,
      "maxTwa": <number knots>,
      "motor": {
        "enable": <boolean>,
        "speed": <number knots>,
        "activationThreshold": <number knots>
      }
    },
    "enrich": <boolean>
  }
}

Response HTTP 201 - Created

Content-Type

application/json

Body

{
  "summary": <object Summary>,
  "routing": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [ <number longitude>, <number latitude> ]
        },
        "properties": <object FeatureProperties>
      }...
    ]
  }
}

When the "enrich" value provided in the request body is false , then the

{}

When "enrich" is set to true in the request body, then the

{
  "startTime": <string w3c_datetime>,
  "endTime": <string w3c_datetime>,
  "totalDistance": <number meters>,
  "totalDuration": <number meters>,
  "avgSpeed": <number meters_per_second>,
  "sailsTimeProportions": {
    "Code 0": <number proportion>,
    "Solent": <number proportion>,
    "Grand Gennaker": <number proportion>,
    "Trinquette": <number proportion>,
    "Foc": <number proportion>,
    "Petit Gennaker":<number proportion>,
  }
}

When the "enrich" value provided in the request body is false , then the

{
  "time": <string w3c_datetime>,
  "heading": <number degrees_north>,
  "weather": [
    {
      "model": <string>,
      "variable": <string>,
      "value": <number meters_per_second>
    }...
  ]
}

When "enrich" is set to true in the request body, then the

{
  "time": <string w3c_datetime>,
  "heading": <number degrees_north>,
  "weather": [
    {
      "model": <string>,
      "variable": <string>,
      "value": <number meters_per_second>
    }...
  ],
  "distanceToWaypoint": <number meters>,
  "timeToWaypoint": <number seconds>,
  "speedOverGround": <number meters_per_seconds>,
  "windSpeed": <number meters_per_seconds>,
  "windDirection": <number degrees_south>,
  "trueWindAngle": {
    "angle": <number degrees>,
    "type": <string tack>
  },
  "distanceFromStart": <number meters>,
  "distanceTillEnd": <number meters>,
  "timeFromStart": <number seconds>,
  "timeTillEnd": <number seconds>,
  "sail": <string>
}

Units and Allowed Values

Ids

• a unique id representing an element, could be an integer or a string

  Strings

• string with no restriction on its content
• date/time string respecting the ISO8601 standard
• Indicates in which order the values array of a polar should be read. It must be either values[speed][angle] or values[angle][speed]
• The weather model that should be used for the routing computation. Allowed values are GFS025, GFS05, GEFS00, CEP0125, CEP025, CEP05, CEP10.
• The weather variables taken into account for the routing computation. Allowed values are 10u, 10v. As of right now, both should be used simultaneously for the routing to work.
• String indicating the tack. Possible values are P for port or S for starboard.

  Numbers

• longitude in degrees
• latitude in degrees
• angle in degrees
• angle in degrees, counting clock-wise from the north
• angle in degrees, counting clock-wise from the south
• distance in meters
• speed in meters per second
• speed in knots
• number between 0 and 1 representation a proportion. Could be set to a value higher than 1 in some cases.
• duration in seconds

Response HTTP 400 - Bad Request

Content-Type

application/json

Body

<string human_readable_error_message>

Response HTTP 500 - Internal Server Error

Nothing relevant here

Example - HTTP 201 - Created

Request

Content-Type** ** application/json

Body See request-body.json

Response

Status Code 201 - Created

Body See response-body.json

Appendix

Polars

4 Fields:

• Wind speeds
• Wind Angles
• Boat speed values for a specific wind speed/angle
• Indexing of the value in the matrix: (values[speed][angle] or values[angle][speed])

Examples

{
  "windAngles": [ 0, 10, 20, 30, ... ],
  "windSpeeds": [ 0, 2, 4, 6, ... ],
  "index": "values[speed][angle]",
  "values": [
    [ 0, 0, 0, ... ],
    [ 0, 0.5, 1.2, ... ],
    ...
  ]
}

SailCharts

Format similar to Polars

6 Fields:

• Wind speeds
• Wind Angles
• Sails
• Boat speed values for a specific wind speed/angle
• Best sail for a specific wind speed/angle
• Indexing of the value both matrices: (values[speed][angle] or values[angle][speed])

Examples

{
  "windAngles": [ 0, 10, 20, 30, ... ],
  "windSpeeds": [ 0, 2, 4, 6, ... ],
  "sails": ["code 0", "J1", "Spi"],
  "index": "values[speed][angle]",
  "values": [
    [ 0, 0, 0, ... ],
    [ 0, 0.5, 1.2, ... ],
    ...
  ],
  "Best sails": [
    [ "J1", "J1", "code0", ... ],
    ...
  ]
}

Routes

A route is a set of waypoints describing mandatory checkpoints (and how to tackle them), coupled to a set of exclusion areas where we cannot navigate.

{ 
  id: <uid>,
  name: <string>,
  description?: <string>,
  waypoints: <GeoJSON>,
  exclusionAreas; <GeoJSON>,
}

Waypoints

A Feature collection of GeoJSON points.

Exclusion Area

A Feature collection of GeoJSON polygones.

Routing Result

A Feature collection of GeoJSON points.