Data are provided under the terms of the Open Government License (OGL), and you can access the data without registering; however, to protect the service, we limit the amount of data that can be downloaded each day. You can access a greater volume of data if you register.
There are two different ways to access the API.
- Anonymous access does not require the user to register, but imposes a lower daily download limit (5000 credits, see below for details).
- Registered access is for users who require longer periods of data, greater numbers of time series, or more frequent downloads.
Anonymous access
This should be suitable for most casual users. Should you wish to download a large volume of data (for example 10 years of data for 50 sites), you can either register or spread this download over a few days.
Registered access
This is suitable for more expert users who require more data or data more frequently. For example you may wish to download all the data for a number of sites in a catchment, or the last few hours of data for all the sites multiple times each day. If you intend to include our data in a web product, you should definitely register.
Optimising your access
Our API function reference gives examples of common API calls and hints to optimise your use of the API.
How the data limits work
Different requests are accorded a credit score, based on the computational expense of servicing the request. The daily download limits set for the anonymous and registered access are determined by their respective credit limits. Not every data request results in data being pulled from the data archive's database; the results of some, more popular, requests are stored in a temporary cache for easy subsequent retrieval.
API Credit system
The API uses a virtual credit system to control access to make sure that no user can request so much data that performance for other users is compromised.
Virtual credits are based on the number of time series points that a request is predicted to return; for example 1 year of daily data will return 365 values, while 1 day of 15-minute data will return 96 values. Metadata requests use a nominal credit amount (1 or 2 credits) for each type of request. Credits are not split and a minimum of one credit is applied for every request.
Credits are calculated as follows:
- Time series data : 1 credit per 1000 data values
- Last values 1 credit per 20 time series
- Station list, parameter list, &c. 1 credit per request
Credits are not split, so requests predicted to return less than 1000 values will result in a single credit being allocated.
Due to the calculation method Gauging and Peak over Threshold time series will calculate the credit cost based on 365 values per year, even though the actual number of values will be less than this.
Example credits for requests:
- 1 year of daily mean flow (365 time series values) : 1 credit
- 3 years of daily mean flow (1095 time series values) : 2 credits
- 1 day of 15-minute rainfall (96 time series values) : 1 credit
- 1 day of 15 minute data for 10 stations, in 1 request : 1 credits
- 1 day’s worth of values for all 15-minute level time series (410 stations, 96 time series values per station) : 40 credits
- Last time series value for 410 time series : 20 credits
- 50 years of daily mean flow (18,250 values) : 19 credits
Allocated Credits
Unregistered users, identified by the IP number the request is sent from, are allocated 5000 credits per day.
Registered users are allocated 10000 credits per day in the first instance. This may be extended if the user can provide sufficient justification for the increase.
If your credit limit for the day is exceeded, then expect the following an error message: Credit limit exceeded for type IP/TOKEN and key your IP or Key
For further protection of the system a maximum of 300,000 data points are allowed in a single request. Requests where the number of points returned are calculated to exceed this value will be refused (error TooManyResults).
For both the maximum number of data points per request and the credit amounts the values are calculated by the system. The values calculated are estimates and not necessarily the exact number of data values returned.