API Documentation
Introduction
The Purpose of the Construction Waste Portal (RESTFUL) Application Programming Interface (API) is to allow Projects to be created, Waste Data to be updated and access to Waste Forecasting data from outwith the Construction Waste Portal Application (CWP). The CWP API has been developed and is maintained by the CWP team.
API End Points
- UPDATE Waste Data
- CREATE Project
- GET Waste Data
- GET Waste Forecast Data
Primary Credentials
A Construction Waste Portal user account with an associated API Token (the API token is generated by Construction Waste Portal for all valid accounts with permissions to access the API).
Error Handling
If a request is invalid, for example it does not contain a required field, an error message will be returned.
Logging
Each request is recorded in a database table. This records the user id, time and type of request, request (text), success/failure of request and response (including any error messages).
|
UPDATE Waste Data
|
|
Fields
|
Example (Python 3.8)
|
|
- username
- required
- String
- project_ref
- required
- String
- company_ref
- required
- String (found in the Details tab in Construction Waste Portal)
- waste_data optional
-project_start_month optional
-project_end_month optional
- JSON
- year: required
- month: required
- num_tonnes: optional
- num_tonnes_general: optional
- num_tonnes_inert: optional
- num_tonnes_timber: optional
- num_tonnes_metal: optional
- num_tonnes_plasterboard: optional
- num_tonnes_plastic: optional
- num_tonnes_other: optional
- recycling_rate: optional
- num_tonnes_soil: optional
- num_tonnes_demo: optional
|
**Waste Data example (JSON)**
``` [{ "year": 2024, "month": 1, "num_tonnes": 25.34, "num_tonnes_general": 15.16, "num_tonnes_inert": 4.3, "num_tonnes_timber": 2.2, "num_tonnes_metal": 0.0 "num_tonnes_plasterboard": 0.0, "num_tonnes_plastic": 0.0, "num_tonnes_other": 0.0, "recycling_rate": 98.67, "num_tonnes_soil": 0.0, "num_tonnes_demo": 0.0, },{ "year": 2024, "month": 2, "num_tonnes": 45.89, "num_tonnes_general": 36.89, "num_tonnes_inert": 14.3, "num_tonnes_timber": 12.2, "num_tonnes_metal": 3.1, "num_tonnes_plasterboard": 0.0, "num_tonnes_plastic": 0.0, "num_tonnes_other": 0.0, "recycling_rate": 96.34, "num_tonnes_soil": 0.0, "num_tonnes_demo": 0.0, },{ "year": 2024, "month": 3, "num_tonnes": 25.78, "num_tonnes_general": 16.89, "num_tonnes_inert": 12.3, "num_tonnes_timber": 9.2, "num_tonnes_metal": 6.1, "num_tonnes_plasterboard": 0.0, "num_tonnes_plastic": 0.0, "num_tonnes_other": 0.0, "recycling_rate": 99.7, "num_tonnes_soil": 0.0, "num_tonnes_demo": 0.0, },{ "year": 2024, "month": 4, "num_tonnes": 78.45, "num_tonnes_general": 56.89, "num_tonnes_inert": 23.3, "num_tonnes_timber": 18.2, "num_tonnes_metal": 13.1, "num_tonnes_plasterboard": 0.0, "num_tonnes_plastic": 0.0, "num_tonnes_other": 0.0, "recycling_rate": 99.99, "num_tonnes_soil": 0.0, "num_tonnes_demo": 0.0, }] ``` **Update Waste Data request example (Python)**
```
import requests, json
try:
## Query Params
query = {
'username': "apitest@constructionwasteportal.com",
'project_ref': "API_Test_1",
'company_ref': "866b8332-2c0b-4465-888b-683c6472426a",
'waste_data': [see above]
}
get_waste_data_endpoint = f"https://app.constructionwaste
portal.com/api/waste_data/update/"
update_waste_data_response = requests.get(get_waste_data_endpoint, params=query)
except Exception as e:
print("Exception: %s", e)
```
|
|
Response: Success or Failure message |
|
|
CREATE Project |
|
Fields |
Example (Python 3.8) |
|
- username
- required
- String
- project_ref
- required
- String
- project_name
- required
- String
- company_ref
- required
- String (found in the Details tab in Construction Waste Portal)
- project_start_month
- required
- Date (format must be YYYY-MM-DD i.e. 2024-01-01 for Jan 1st 2024)
- project_end_month
- required
- Date (format must be YYYY-MM-DD i.e. 2024-04-01 for April 1st 2024)
- project_type
- optional
- String (either "Buildings" or "Civils")
- project_postcode
- optional
- String
- gifa
- optional (preferred for Buildings Projects for Waste KPIs)
- Integer/Decimal (10000, 10000.00)
- value
- optional (preferred for Civils Projects for Waste KPIs)
- Integer/Decimal (25000000, 25000000.00)
- estimated_tonnes_of_waste
- optional
- Integer/Decimal (800, 800.00)
- estimated_embodied_carbon
- optional
- Integer/Decimal (800, 800.00)
- procurement route
- optional
- String: MUST be one of the following:
- "Not Applicable"
- "Non-Framework"
- "CWM"
- "LCP"
- "NEPO"
- "NWCH"
- "NWCP"
- "SCAPE"
- "SCF"
- "SEWSCAP"
- "SWWRCF"
- "YORhub"
- region
- optional
- String: MUST be one of the following:
- "Not Specified"
- "East Midlands"
- "East of England"
- "London"
- "North East"
- "North West"
- "Scotland"
- "South East"
- "South West"
- "Wales"
- "West Midlands"
- "Yorkshire and The Humber"
- sector
- optional
- String: MUST be one of the following:
- "Civil Engineering"
- "Commercial"
- "Education"
- "Healthcare"
- "Industrial"
- "Leisure"
- "Manufacturing"
- "Mixed Use Dev"
- "Offices"
- "Public Buildings"
- "Residential"
- "Retail"
- "Fit Out"
- "Unknown"
- client
- optional
- String
- contract_number
- optional
- String
- waste_data
- optional
- JSON
- year: required
- month: required
- num_tonnes: optional
- num_tonnes_general: optional
- num_tonnes_inert: optional
- num_tonnes_timber: optional
- num_tonnes_metal: optional
- num_tonnes_plasterboard: optional
- num_tonnes_plastic: optional
- num_tonnes_other: optional
- recycling_rate: optional
- num_tonnes_soil: optional
- num_tonnes_demo: optional
|
**Create Project request example (Python)**
```
import requests
try:
query = {
'username': "apitest@constructionwasteportal.com",
'project_ref': "API_Test_1",
'project_name': "API_Test_1",
'company_ref': "866b8332-2c0b-4465-888b-683c6472426a",
'project_start_month': "2024-01-01",
'project_end_month': "2024-04-01",
}
create_project_endpoint = f"https://app.construction
wasteportal.com/api/waste_data/update/"
create_project_response = requests.get(create_project_endpoint, params=query)
except Exception as e:
print("Exception: %s", e)
|
|
Response: Success or Failure message
|
|
|
GET Waste Data
|
| Fields | Example (Python 3.8) |
|
- username
- required
- String
- project_ref
- required
- String
- company_ref
- required
- String (found in the Details tab in Construction Waste Portal)
|
**Get Waste Data request example (Python)**
```
import requests
try:
query = {
'username': "apitest@constructionwasteportal.com",
'project_ref': "API_Test_1",
'company_ref': "866b8332-2c0b-4465-888b-683c6472426a"
}
get_waste_data_endpoint = f"https://app.constructionwasteportal.com/api/waste_data/"
get_waste_data_response = requests.get(get_waste_data_endpoint, params=query)
except Exception as e:
print("Exception: %s", e)
```
|
|
Response:
(List of) JSON Object(s) (waste data only).
{
"month": "2024-07-01",
"num_tonnes": "35.00",
"num_tonnes_general": "20.00",
"num_tonnes_inert": "10.00",
"num_tonnes_timber": "5.00",
"num_tonnes_metal": null,
"num_tonnes_plasterboard": null,
"num_tonnes_plastic": null,
"num_tonnes_other": null,
"recycling_rate": null,
"num_tonnes_soil": null,
"num_tonnes_demo": null
}
|
|
|
GET Waste Forecast Data
|
| Fields | Example (Python 3.8) |
|
- username
- required
- String
- postcode
- required
- String (full or partial valid postcodes are accepted i.e. N19 3JR, N193JR, N19)
- sector
- required
- String: MUST be one of the following:
- "Civil Engineering"
- "Commercial"
- "Education"
- "Healthcare"
- "Industrial"
- "Leisure"
- "Manufacturing"
- "Mixed Use Dev"
- "Offices"
- "Public Buildings"
- "Residential"
- "Retail"
- "Fit Out"
- gifa
- required
- Integer/Decimal (10000, 10000.00)
- value
- required
- Integer/Decimal (25000000, 25000000.00)
|
**Get Waste Forecasting Data request example (Python)**
```
import requests
try:
query = {
'username': "apitest@constructionwasteportal.com",
'postcode': "N19 3JR",
'sector': "Offices",
'gifa': "10000",
'value': "2000000"
}
get_waste_forecast_data_endpoint = f"https://app.constructionwasteportal.com/api/waste_data/waste_forecasting/"
get_waste_forecasting_data_response = requests.get(get_waste_forecast_data_endpoint, params=query)
except Exception as e:
print("Exception: %s", e)
|
|
Response:
- JSON Object:
- "number_tonnes"
- "waste_breakdown"
- "embodied_carbon"
- "waste_management_
emissions"
- "number_standard_
skips_required"
|
|
Last updated
Our API documentation was last updated on : 17/09/2024