JavaScript is required for this website to work properly.

API reference

The Oxford Rivers Portal has its own application programming interface (API) which intakes data from online and offline sources and processes it into a common json format.

API calls you can make through the oxford rivers API are:

  1. /getDatasets (https://oxfordrivers.ceh.ac.uk/getDatasets)
    • Returns a json array of the datasets and their metadata available to the portal
  2. /getDeterminands (https://oxfordrivers.ceh.ac.uk/getDeterminands)
    • Returns a json array of the determinands available to the portal and which dataset(s) they belong to
  3. /getSites (e.g.: https://oxfordrivers.ceh.ac.uk/getSites?datasetID=rainfall)
    • datasetID must be one of the following as per the datasets query: ea_bathing_water, edm, rainfall, fft, ea_water_quality, ea_lf_sonde, ea_wq_sonde, freshwater_watch, ea_flood_warnings
    • Returns a json file listing all of the sites belonging to that datasetID that are included in the portal. 'Features' is an array of objects, each object includes 'geometry' and 'property' properties, specifying the location of the site, the site id and the name. 'Property' may contain additional properties depending on the datasetID. This call is used in the portal to populate the map with site icons.
  4. /getDataforDate (e.g. https://oxfordrivers.ceh.ac.uk/getDataForDate?datasetID=edm&date=2024-07-31)
    • datasetID must be one of the following (as per the datasets query where map === true): edm, rainfall ea_lf_sonde; date must be a date after 2021 formatted YYYY-MM-DD.
    • Returns a json file listing all the values for sites of that datasetID on that day. 'Data' is an array of objects, each containing 'id' and 'value' properties, 'id' contains the site id and 'values' contains relevant daily data for that dataset. This call is used in the portal to colour icons on the map and put information in hover-over tooltips based on the date selected.
  5. /getTimeseries (e.g. https://oxfordrivers.ceh.ac.uk/getTimeseries?siteID=Oxford&datasetID=fft)
    • datasetID must be one of the following (as per the datasets query where graph === true): ea_bathing_water, edm, rainfall, fft, ea_water_quality, ea_lf_sonde, ea_wq_sonde, freshwater_watch; siteID must be a valid siteID (i.e. returned by getSites as an 'id' property). For ea_water_quality, freshwater_watch and ea_wq_sonde, ?determinand={deterimand_id} should also be specified. A list of available determinands for ea_water_quality and ea_wq_sonde sites is returned as a property in the getSites call. freshwater_watch can be used with the following determinands: chemical_nitrate, chemical_phosphate, optical_secchi_turbidity.
    • Returns a json listing of all the available data for that site from 2021-01-01 to the current day. 'Data' is an array of objects representing measurements, each object has a 'datetime' and 'value' property, and may contain additional properties such as ''units' or 'qualifiers' depending on the datasetID. This call is used in the portal to draw timeseries plots when you click on an icon in detailed view.

Many of the Oxford Rivers Portal API calls use other APIs to retrieve data. See the understanding the data section to read about of all the APIs currently used by the portal.

To see the API used in Python, have a look at the Casestudy: FFT and EDM