Technical Overview

Introduction to the ADMIRALTY API Developer Portal

The ADMIRALTY APIs are available via our ADMIRALTY API Developer Portal. This gives ADMIRALTY the facility to control access, provide analytics and a platform for detailed documentation of the APIs, as well as issue tracking.

When you first arrive at the ADMIRALTY API Developer Portal, you will need to sign up. Please see the ADMIRALTY API Start Up Guide for details.

Products

ADMIRALTY APIs access is controlled by subscriptions. The Products page lists the environments you are enabled to use.

To subscribe to a Product, select the Product you require access to.

Clicking on a Product link will take you to a page where you can view the APIs within the product and subscribe.

Click the Subscribe button to personalise the Subscription name. You cannot complete your subscription of any product without reading and accepting the Terms and Conditions.

Once you have done so, you will be taken to your profile. Within this page there is a subscriptions section where you will be able to see and manage your Primary and Secondary subscription key.

Any products you have subscribed to will be visible in the APIs tab on the main menu bar.

API Documentation

The API Documentation page lists all the operations that are available with an API, along with details for each operation. Selecting an operation on the left-hand side will show the detail of:

• Request URL
• Request parameters If any request parameters are applicable, these will be detailed here.
• Request headers Request headers including subscription keys will be detailed here.
• Request body If a request is required to have a body, the schema and examples will be documented here.

• Response Codes with sample responses. We use standard HTTP response codes. For example, if the request was successful, we will return 200 OK, but if the authentication credentials are incorrect we will return 401 Unauthorized.

  Most responses may return either Content-Type application/json or application/zip depending on the situation. Where an application/json response is expected, the documentation will provide a sample and a schema for the response body where applicable. Errors that are not fully defined by the HTTP Status Code will return with Content-Type application/json with a json object that provides more details about the error.

• Code samples

In general, errors are defined by the HTTP response code and reason phrase. If there is additional information about the error, an error object will be returned which has an array of errors which gives the source and detail of each individual error.

Try It

There is a Try It button for each operation that takes you to a page where you can specify the parameters and send a request to see what response you will get. Note, this does construct and send a request to the service and will be included in any quotas.

The Try It tool will automatically fill in the Ocp-Apim-Subscription-Key for you using your current user's subscription keys. You can select either the primary or secondary key in the Authorization section.

At the bottom of the Try It tool, you can see the HTTP request generated with all the URL parameters, headers and body required for the request. This sample request is updated as you change the parameters in the form.

Download API Definition

You can download an API definition file for the entire API by clicking the API definition button on the top right of the page. Currently you can download the API definition as either a Swagger Open API definition, or a Web Application Description Language ( WADL)

Code Samples

At the bottom of the detailed description for each operation, there are code samples for using the API via 8 different languages: Curl, C#, Java, JavaScript, ObjC, PHP, Python and Ruby. These code samples are intended to give you a jump start to using the APIs using your own development stack. You will need to ensure that you update the code to include the correct parameters (e.g. for the GetTidalEvents operation, you will need to ensure that the stationId in the url is replaced with the actual station ID you are getting the tidal events for). For all operations, you will need to ensure the Ocp-Apim-Subscription-Key header is correctly populated with your subscription key.

Profile and Subscriptions

To view your profile details, click on your name in the top right and select Profile. The profile page shows:

• Profile details: email and name associated with the account
• A button to change the password associated with the account
• A link to your own analytics reports
• Subscriptions you currently have

Subscription Keys

Once you have a subscription to a product, to use the APIs you will need a subscription key. These can be found on your profile page. Each subscription will list two keys, a primary key and a secondary key. Either subscription key can be used to access the APIs. To get the subscription key, simply click Show, and copy the subscription key to your own systems.

Should you need to change either of your subscription keys for any reason (e.g. you believe it may have been compromised), simply click the regenerate button an a new subscription key will be generated.

Analytics

A report of your usage of the APIs can be found in the Analytics section of your Profile, click on the Analytics reports button on your Profile page. The Analytics gives you an indication of how much you are using each of the different APIs and how many calls are returning errors. Analytics data is updated roughly every 15 minutes and you can view data for Today, Yesterday, Last 7 Days, Last 30 Days or last 90 Days.

Issues

The Developer Portal provides an issue tracker that you can use to raise technical issues during development of your solution using the B2B REST APIs. If you have a live issue, please contact customerservices@ukho.gov.uk. Issues are publicly visible and anyone who is logged into the system can add comments to an issue, allowing collaboration between developers and ADMIRALTY. Please also use Issues to identify errors or omissions in the documentation.

To create an issue, click the Report Issue button on the Issues page. Here you can provide a title and detailed description of the issue and attach supporting documents as required. Please provide as much detail as possible, code samples, detailed errors (including error messages), etc. Remember that issues are publicly visible, so don't post your subscription keys as these should be kept secret.

Once an issue has been reported, users can add comments to the issue or attach additional supporting documents using the box at the bottom of the issue details page.

Quotas

To protect the service from abuse, all developers are allocated a quota of calls. Please see the Terms and Conditions of the relevant product for quota limits. Once you have reached 75% of your quota, you will receive an email warning that you are approaching your usage limit. Once you exceed your quota, all further calls to the API will return HTTP 403 Quota Exceeded until the next quota period. The body of the response will tell you how long you have until your quota is refreshed:

{
    "statusCode": 403,
    "message": "Out of call volume quota. Quota will be replenished in 01:06:40."
}

HTTP Headers

Request Headers:

All required request headers are detailed in the API documentation. Some of the common headers are also described here:

• Ocp-Apim-Subscription-Key - Subscription key which provides access to the APIs. Found in your Profile.

Browser Based Cross Origin Resource Sharing and Key Privacy

All modern browsers enforce security when data for www.yourwebsite.com is provided by www.someoneElsesWebsite.com.

As your key is embedded in your application / webpage, it may be at risk of others to use it.

By putting the API-accessing code on your server, you can avoid the browsers triggering this feature.

The diagram on the right shows that when your key is embedded in your server layer, it is protected from others by the server’s security and your authentication. End users do not see your key, and thus cannot use your quota.

To find out more, search for CORS or Cross Origin Resource Sharing.

Branding Requirements for Developers

Where technically possible, the following acknowledgement shall be included, such that it is visible to end-users:

Contains ADMIRALTY® tidal data: 
© Crown Copyright and database right.

The font is Arial and minimum 12 px text size. The statement should be split onto two lines. This font colour can either be ADMIRALTY blue, black, or white. It can also be transparent if the background makes the statement visible.