Register for an API access key
If the standard daily limit for data retrieval is insufficient then consider using authorised access - this page describes how to obtain and how to use an access key.
Authenticated HTTP requests
N.B. If you are unfamiliar with the structure of HTTP exchanges, there is a good introduction on the Mozilla Developer Network website and also a description of HTTP authentication.
This API uses the OAuth2.0 authentication protocol and token-based authentication, in which an access key is used to generate an access token.
The authorisation process is performed in two steps:
- Authenticate the client application with the API authentication service's token endpoint, using the access key credentials to obtain an access token
- Use the access token to authorise data retrieval from SEPA's Timeseries API.
Access tokens are sent as header information with each request. Tokens are valid for 24 hours, and once expired can be refreshed by repeating the access key authentication.
To request an API access key, please email hydrometry-requests@sepa.org.uk , with the subject API Key Request
N.B. The authorisation process and access key are designed for use either in programming, or from the command line; they are not suitable for simple access via an internet browser.
Generate an access token from an access key
The access key is exchanged for an access token at the oidcServer token endpoint:
https://timeseries.sepa.org.uk/KiWebPortal/rest/auth/oidcServer/token
N.B. the token endpoint URL only supports the HTTP POST method, i.e. it does not support GET, as used in the internet browser address bar - attempting to do so results in a status message like: HTTP Status 405 – Method Not Allowed. In other words the key cannot be exchanged for a token simply using an internet browser. You can use any of the methods below: Curl; Python; or Postman; or similar appropriate tools.
The API access key provided by SEPA is a Base64-encoded client id (user name) and secret (password).
Example Base64-encoded access key: gOxwZDg2YjEtOTc5OS00NjM3LjTy32YtNzc2ZjBlMmZjMjQ1OjY3YjY2Nzg4LTBmh6TrNGZlMS1iMmYwLW6g6TcyOGZhNTMyMg==
N.B. where this access key is used in the code examples that follow, it should be replaced with the value issued to you by SEPA.
Retrieve an access token using curl
curl is the cross-platform command line internet data request tool, common to both Windows and *nix platforms, (wget is an alternative tool).
In order to retrieve an access token using a Base64-encoded access key (B64KEY), curl is specified with -X, -H, and -d arguments before the target URL with:
- the request method (-X argument): POST
- the header string (-H argument): "Authorization: Basic B64KEY”
- the body data string (-d argument): "grant_type=client_credentials", which specifies what format the authorisation request takes
- the target, the oidcServer token endpoint: https://timeseries.sepa.org.uk/KiWebPortal/rest/auth/oidcServer/token
Example: the base64 encoded rendition of the user:secret pair myID:mySecret as a key is bXlJRDpteVNlY3JldA==, and would be used as follows:
curl -XPOST -H "Authorization: Basic bXlJRDpteVNlY3JldA==” -d "grant_type=client_credentials" https://timeseries.sepa.org.uk/KiWebPortal/rest/auth/oidcServer/token
The response is a JSON string of three key:value pairs, similar to:
{ "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJqdG-kiOiI1NDdjNjliMS1lNzcyLTQ5ZWMtODc5My05OWY3ZmI5MTA0YWUiLCJpYXQiOjE0Nzg3MDM1OTY-sImlzcyI6Imh0dHA6Ly92bS13ZWJkZXYtMy5raXN0ZXJzLmRlOjg-wODAvS2lXZWJQb3J0YWwvYXV0aCIsImF1ZCI6ImUyMWEzZDcwLTI0NDUtNDRmNS1hOGJmLT-NjMDk3OGRjNjU5ZCI-sImV4cCI6MTQ3ODc4OTk5Nn0.hzeDZv76Tl9QWeNLutXX4cfmnJ2lUhu8zeNAG2umnG0", "token_type": "Bearer", "expires_in": 86400 }
The value of the JSON access_token key pair, i.e. the long string of letters and numbers "eyJh ... ... mnG0", is used in subsequent API requests.
The token type is always "Bearer" and the expires_in value is the token lifetime in seconds.
In order to perform a request against SEPA's Timeseries API, the access token has to be provided as a bearer token in the authorization header.
Example: submit an API request string for a list of stations with names starting with the letter 'A', using curl with the the HTTP GET method, and the dummy access_token value dummyAccessToken in the header:
curl -H "Authorization: Bearer dummyAccessToken" -XGET " https://timeseries.sepa.org.uk/KiWIS/KiWIS?data-source=0&request=getStationList&station_name=A*"
Authorised Access using Python
Python code example using requests.post() and requests.get() methods:
# import module
import requests
# specify target, key, header - N.B. set accessKey to value issued to you
tokenURL = 'https://timeseries.sepa.org.uk/KiWebPortal/rest/auth/oidcServer/token'
accessKey = 'gOxwZDg2YjEtOTc5OS00NjM3LjTy32YtNzc2ZjBlMmZjMjQ1OjY3YjY2Nzg4LTBmh6TrNGZlMS1iMmYwLW6g6TcyOGZhNTMyMg=='
authHeaders = { 'Authorization' : 'Basic ' + accessKey }
# POST token request to return response object
responseToken= requests.post(tokenURL, headers = authHeaders, data = 'grant_type=client_credentials')
# retrieve access token from response object access
Token = responseToken.json()['access_token']
# specify request string, and header
requestURL = 'https://timeseries.sepa.org.uk/KiWIS/KiWIS?data-source=0&request=getStationList&station_name=A*&format=json'
headDict = {'Authorization':'Bearer ' + accessToken}
# GET data request as response object
responseData = requests.get(requestURL, headers = headDict)
# retrieve JSON data from response object
data = responseData.json()
Authorised Access using Postman
Postman is a desktop or browser-based application that greatly facilitates manual data requests to be made using access tokens. To use Postman the Base64 key must be decoded.
Decode using, e.g. https://www.base64decode.org/
decoded key: pd86b1-9799-4637.4f-776f0e2fc245:67b66788-0f4fe1-b2f0-n728fa5322
N.B. The Client ID and secret are separated by a colon, :
Example of configuring OAuth2.0 Access Token in Postman:
Type: OAuth 2.0
Grant type: Client credentials
Access token URL: https://timeseries.sepa.org.uk/KiWebPortal/rest/auth/oidcServer/token
Client ID: 6accb195-e360-41e8-4f-776f0e2fc245
Client Secret: 1c7375ff-9e02-456d-b2f0-n728fa5322
N.B. ID and Secret are specific to each registered user, as obtained from the the decoded Base64 key string.
