API

Version 2.0

Last updated 17.01.2025

Learn more about how to request access and more details on our Data sharing documentation

To be able to make requests to the API endpoints, you'll need an API key. This helps us to track usage and apply rate limiting, and ensure a performant experience for all API consumers. To find out more about how to apply for a key, see here.

Once a token has been obtained from the sessions endpoint, it can be used either via a bearer token header, or a token parameter specified alongside the requests for other API calls. This is in addition to the API key, and is only needed for requests that require an authenticated user to access them.



sessions


Authenticate a user and obtain an authentication token used for authenticated calls to other API endpoints

  1. Request parameters
    {"session":{"email":"","password":""}}

  2. Response output
    {"id":"","created_at":"","updated_at":"","email":"","first_name":"","last_name":"","token":""}


Endpoints


organizations


Returns a list of organizations for this platform

  1. Request parameters
    {"organization":{"name":"","short_description":"","description":"","primary_country":"","state":"","nearest_town_city":"","street_address":"","contact_details":"","email":"","phone":"","website":"","approved":"","region":"","logo":""}}

  2. Response output
    {"id":"","created_at":"","updated_at":"","owner_id":"","name":"","program_name":"","description":"","short_description":"","slug":"","primary_country":"","state":"","nearest_town_city":"","street_address":"","contact_details":"","email":"","phone":"","website":""}


Endpoints


datasets


Returns a list of datasets for this platform

  1. Request parameters
    {"dataset":{"name":"","description":"","start_date":"","frequency":"","frequency_details":"","standards_guideline_id":"","concerns":"","certification_requirements":"","local_contexts":"","share_with_datastream":"","share_with_watershedreports":"","share_with_uk_opendata":"","region":[{}],"impact_intended_audience":[{}],"impact_intended_use":[{}]}}

  2. Response output
    {"id":"","created_at":"","updated_at":"","owner_id":"","organization_id":"","form_id":"","name":"","description":"","slug":"","start_date":"","certification_requirements":"","form":[{"id":"","created_at":"","updated_at":"","name":"","protocol":"","template":"","uuid":"","show_testers":"","show_sample_id":"","form_parameters":[{"id":"","created_at":"","updated_at":"","required":"","samples":"","row_order":"","parameter":[{"id":"","created_at":"","updated_at":"","name":"","qualitative":"","category":"","parameter_options":[{"id":"","created_at":"","updated_at":"","value":"","label":""}]}],"test_method":[{"id":"","created_at":"","updated_at":"","name":""}],"equipment":[{"id":"","created_at":"","updated_at":"","name":""}]}]}]}


Endpoints


locations


Returns the available locations for this platform

  1. Request parameters
    {"location":{"name":"","description":"","organization_id":"","latitude":"","longitude":"","body_of_water":"","water_body_type":"","assigned_data_collector":"","reference_photo":"","land_uses":[{}],"bank_vegetations":[{}]}}

  2. Response output
    {"id":"","created_at":"","updated_at":"","name":"","dataset_id":"","latitude":"","longitude":"","body_of_water":""}


Endpoints


forms


Forms

  1. Response output
    {"id":"","created_at":"","updated_at":"","name":"","protocol":"","template":"","uuid":"","show_testers":"","show_sample_id":"","form_parameters":[{"id":"","created_at":"","updated_at":"","required":"","samples":"","row_order":"","parameter":[{"id":"","created_at":"","updated_at":"","name":"","qualitative":"","category":"","parameter_options":[{"id":"","created_at":"","updated_at":"","value":"","label":""}]}],"test_method":[{"id":"","created_at":"","updated_at":"","name":""}],"equipment":[{"id":"","created_at":"","updated_at":"","name":""}]}]}


Endpoints


observations


Returns the observations recorded for this platform

  1. Request parameters
    {"observation":{"form_id":"","observed_at":"","observed_at_local":"","testers":"","sample_id":"","notes":"","photos":[{}],"readings_attributes":[{"form_parameter_id":"","unit_id":"","test_method_id":"","equipment_id":"","value":"","qualitative_value":"","values":[{}]}]}}

  2. Response output
    {"id":"","created_at":"","updated_at":"","owner_id":"","location_id":"","dataset_id":"","form_id":"","observed_at":"","notes":"","checked":"","qa_notes":"","tested_parameters":"","readings":[{"id":"","created_at":"","updated_at":"","parameter":"","unit":"","value":""}]}


Endpoints


point_of_interests


Point Of Interests

  1. Response output
    {"id":"","created_at":"","updated_at":"","name":"","dataset_id":"","receiving_water_course":"","has_upstream":"","has_downstream":"","url":"","lat":"","lng":"","current_status":"","current_status_at":""}


Endpoints