Skip to content

Waypoints

The Route-Weather-API &waypts= and &drive= arguments both take one or more ',' delimited waypoint definitions as here described. The waypoint syntax is used by the Route-Weather-API endpoints to receive waypoint locations and times along routes. There are two basic forms for the syntax:

  • (<location>;<time>) location and time at this waypoint
  • (<location>;<speed>) location and speed travelled towards this waypoint

location syntax

The <location> part of the syntax takes two forms:

  • lat;lon Latitude northing and longitude easting value separated by a ;. The following example sets initial waypoint at the coordinate of Reykjavik on 1 Jan 2018, and destination coordinate of London on 2 Jan 2018.
Example 
&waypts=(64.1;-21.9;18-01-01T12:00),(51.5,-0.1;18-01-02T12:00)
  • address , a location name or address, in which case the service will resolve its northing and easting coordinates using geolocation services such as the Google location API. The following example sets the initial waypoint at the coordinates of Reykjavik on 1 Jan 2018, and desination coordinate of London on 2 Jan 2018.
Example 
&waypts=(Reykjavik;18-01-01T12:00),(London;18-01-02T12:00)

time syntax

The <time> part of the syntax can take a few forms:

Example 
&waypts=(Reykjavik;18-01-01T12:00)
  • UNIX time stamp - Scalar number of seconds that have passed since the beginning of 00:00:00 UTC on 1 January 1970. This is the most common form of universal time applied in most computer languages. UNIX time stamps are also used for time values in API responses.
Example 
&waypts=(Reykjavik;1514808000)
  • Time Semantics - For convenience, the following semantic time statements are provided:
    • now - the current UTC time
    • initial_time - the forecast model (default or first mentioned in params list) initial time
    • now_plus_<N>h - UTC now forward N (float) hours
    • now_minus_<N>h - UTC now subtact N (float) hours
    • prev_plus_<N>h - time coordinate of previous waypoint forward N (float) hours
Example

Leaving Reykjavik at current UTC time, arriving 24 hours later in London: 

&waypts=(Reykjavik;now),(London;prev_plus_48h)
Leaving Reykjavik at the forecast's initial time, passing London at current UTC time, then arriving in Madrid at a specified ISO-8601 time stamp: 
&waypts=(Reykjavik;initial_time),(London;now),(Madrid;2018-01-01T12:00)

  • non-ISO notation - In the current version more flexible time notations are accepted. These notations include variants of ISO-8601, using two number year notations yy as opposed to the official four number notations yyyy. Also it is currently allowed to use /, -, : and T delimiters interchangeably. Some of the following alternative notations are currently accepted,

    • yyyy/mm/dd-HH:MM
    • yy/mm/d-HH:MM
Warning

Non-ISO time notations are planned to be rescinded in future versions of the Route-Weather-API. The ISO-8601 notation described above is therefore adviced for operational codes.

speed syntax

An average speed between two waypoints can be used to indicate a time at a waypoint position. The (<location>;<speed>) form can be applied to any waypoint except the first waypoint in a route. I.e. the first waypoint must indicate a time of departure, while any subsequent waypoint can have a speed assigned towards that waypoint as needed. When receiving speed notation, the Route-Weather-API service will derive the waypoint time from the time travelled from the preceding waypoint location.

The speed syntax is a scalar number followed by a unit of speed. The following forms are currently accepted:

  • <S>kn units of knots (nautical miles per hour)
  • <S>kt same as <S>kn, kt being a common alternative notation for knots
  • <S>kph units of kilometers per hour
  • <S>mph units of miles per hour (imperial and US measure)
Example

Leaving Reykjavik at current UTC time, travelling to London at 16.3 knots: 

&waypts=(Reykjavik;now),(London;16.3kn)