TidalWebService

API change history

The UKHO Tidal Web Service API (TWS-API) is the world's most comprehensive tidal prediction interface, providing consumers with fast, accurate, accessible tidal height and tidal stream predictions and data for more than 7,000 ports and 3,000 tidal streams worldwide.

Stations

Returned format is a standard GeoJSON FeatureCollection. The tidal station number is used as the GeoJSON feature Id. Each feature has point geometry. The following custom properties are returned:

  • Name - tidal station name
  • StationType - TidalPortStandardHarmonic, TidalPortStandardNonHarmonic, TidalPortSecondaryHarmonic, TidalPortSecondaryNonHarmonic, TidalStreamHarmonic, TidalStreamNonHarmonic
  • Country - the country that provided the data for the tidal station
  • ATTBias - offset from local timezone (as defined by Admiralty Tide Tables) to UTC, in minutes

Ports only

  • Footnote - footnote text
  • HeightsAvailable - boolean to indicate if continuous heights are available for this station

The availability of the following properties varies by port:

  • HAT - Highest Astronomical Tide (metres)
  • LAT - Lowest Astronomical Tide (metres)
  • MeanHighestHighWater - Mean Highest High Water (MHWS / MHHW) (metres)
  • MeanLowestHighWater - Mean Lowest High Water (MHWN / MLHW) (metres)
  • MeanHighestLowWater - Mean Highest Low Water (MLWN / MHLW) (metres)
  • MeanLowestLowWater - Mean Lowest Low Water (MLWS / MLLW) (metres)
  • MeanSeaLevel - Mean Sea Level (metres)

Try it

Request

Request URL

Request parameters

  • string

    Valid API key

  • (optional)
    string

    The type of station to get

  • (optional)
    number

    Format - double. Geodetic latitude

  • (optional)
    number

    Format - double. Geodetic latitude

  • (optional)
    number

    Format - double. Longitude

  • (optional)
    number

    Format - double. Longitude

Request body

Responses

200 OK

OK

Representations

{
  "features": [
    {
      "geometry": {
        "Type": "Point"
      },
      "id": "string",
      "properties": {},
      "bbox": [
        0.0
      ],
      "crs": {
        "Type": "unspecified"
      },
      "type": "Point"
    }
  ],
  "bbox": [
    0.0
  ],
  "crs": {
    "Type": "unspecified"
  },
  "type": "Point"
}
{
  "type": "object",
  "properties": {
    "features": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "geometry": {
            "type": "object",
            "properties": {
              "Type": {
                "enum": [
                  "Point",
                  "MultiPoint",
                  "LineString",
                  "MultiLineString",
                  "Polygon",
                  "MultiPolygon",
                  "GeometryCollection",
                  "Feature",
                  "FeatureCollection"
                ],
                "type": "string",
                "readOnly": true
              }
            }
          },
          "id": {
            "type": "string"
          },
          "properties": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          },
          "bbox": {
            "type": "array",
            "items": {
              "format": "double",
              "type": "number"
            }
          },
          "crs": {
            "type": "object",
            "properties": {
              "Type": {
                "enum": [
                  "unspecified",
                  "name",
                  "link"
                ],
                "type": "string",
                "readOnly": true
              }
            }
          },
          "type": {
            "enum": [
              "Point",
              "MultiPoint",
              "LineString",
              "MultiLineString",
              "Polygon",
              "MultiPolygon",
              "GeometryCollection",
              "Feature",
              "FeatureCollection"
            ],
            "type": "string"
          }
        }
      }
    },
    "bbox": {
      "type": "array",
      "items": {
        "format": "double",
        "type": "number"
      }
    },
    "crs": {
      "type": "object",
      "properties": {
        "Type": {
          "enum": [
            "unspecified",
            "name",
            "link"
          ],
          "type": "string",
          "readOnly": true
        }
      }
    },
    "type": {
      "enum": [
        "Point",
        "MultiPoint",
        "LineString",
        "MultiLineString",
        "Polygon",
        "MultiPolygon",
        "GeometryCollection",
        "Feature",
        "FeatureCollection"
      ],
      "type": "string"
    }
  }
}

400 Bad Request

Bounding box not fully specified

401 Unauthorized

No API key was supplied, or it wasn't valid

Code samples

@ECHO OFF

curl -v -X GET "https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}?type={string}&north={number}&south={number}&east={number}&west={number}"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);


            // Request parameters
            queryString["type"] = "{string}";
            queryString["north"] = "{number}";
            queryString["south"] = "{number}";
            queryString["east"] = "{number}";
            queryString["west"] = "{number}";
            var uri = "https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}&" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}");

            builder.setParameter("type", "{string}");
            builder.setParameter("north", "{number}");
            builder.setParameter("south", "{number}");
            builder.setParameter("east", "{number}");
            builder.setParameter("west", "{number}");

            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "type": "{string}",
            "north": "{number}",
            "south": "{number}",
            "east": "{number}",
            "west": "{number}",
        };
      
        $.ajax({
            url: "https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}&" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"type={string}",
                         @"north={number}",
                         @"south={number}",
                         @"east={number}",
                         @"west={number}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}');
$url = $request->getUrl();

$headers = array(
    // Request headers
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'type' => '{string}',
    'north' => '{number}',
    'south' => '{number}',
    'east' => '{number}',
    'west' => '{number}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
}

params = urllib.urlencode({
    # Request parameters
    'type': '{string}',
    'north': '{number}',
    'south': '{number}',
    'east': '{number}',
    'west': '{number}',
})

try:
    conn = httplib.HTTPSConnection('ukho.azure-api.net')
    conn.request("GET", "/tides/api/v1/Stations?api_key={api_key}&%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
}

params = urllib.parse.urlencode({
    # Request parameters
    'type': '{string}',
    'north': '{number}',
    'south': '{number}',
    'east': '{number}',
    'west': '{number}',
})

try:
    conn = http.client.HTTPSConnection('ukho.azure-api.net')
    conn.request("GET", "/tides/api/v1/Stations?api_key={api_key}&%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://ukho.azure-api.net/tides/api/v1/Stations?api_key={api_key}')

query = URI.encode_www_form({
    # Request parameters
    'type' => '{string}',
    'north' => '{number}',
    'south' => '{number}',
    'east' => '{number}',
    'west' => '{number}'
})
if query.length > 0
  if uri.query && uri.query.length > 0
    uri.query += '&' + query
  else
    uri.query = query
  end
end

request = Net::HTTP::Get.new(uri.request_uri)
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body