API Reference

The Dsposal API is organized around REST. Our API has predictable resource-oriented URLs, accepts HTTP requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can start using the Dsposal API for free in a testing or live environment and switch a paid plan later on, should you need to. The API is using Dsposal's live data, so you always have access to the most recent data available.

The Dsposal API is centered around Compliance in the Waste Industry, which essentially means that will be able to do the following calls:

List Compliance Codes
Operational
List Compliance Codes by type, e.g. European Waste Catalogue Codes - Subchapters and Chapters (EWC), Recovery and Disposal Codes (R/D Codes) and Hazard Property Codes (H/P) Codes
Validate Compliance Codes
Operational
Validate Compliance Codes by type, e.g. European Waste Catalogue Codes (EWC), Recovery and Disposal Codes (R/D Codes) and Hazard Property Codes (H/P) Codes
Autocomplete Compliance Codes
Operational
Provides suggestions for Compliance Codes by type, e.g. European Waste Catalogue Codes (EWC), Recovery and Disposal Codes (R/D Codes) and Hazard Property Codes (H/P) Codes
Compliance Search
Operational
Searches our Compliance Dataset for Waste Codes, Waste Descriptions and our Waste Thesaurus (tags)

Authentication

The Dsposal API uses Basic Auth to authenticate requests by using your email as the username and your API key as the passowrd. You can view and manage your API key in the Dsposal Dashboard.

Your API key carries many privileges, so be sure to keep it secure! Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, and so forth. Others using your API Key can result in other using using up all your available Quota for your plan.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. (403 Fordidden)

Generating an API Key

  1. Create a new (unlicensed) site in your Dashboard. (You need to create a company brand entity against your account for billing purposes, see gif below)
  2. Navigate to the Developer Tab
  3. Click Generate API Key
  4. Your Key will be generated according to the following format API_XXXX-XXXX-XXXX-XXXX
  5. By Creating an API Key, will be automatically subscribed to the Free API Plan which grants you 500 free API Calls per month. You can scale up or out between plan at any given time.

Create a Company (Brand)

Create an API Key for your Company

API Key Management

  1. All the API Key information and management options can be found in the Developer Tab
  2. You can scale in and out to bigger or smaller plans at any time.
  3. You can view the API's current usage and also the API History Usage (calls made, dates, etc.)
  4. Only Company Administrators have access to the Developer Tab
  5. Once the API key is upgraded to a paid plan by an Administrator, only said Administrator can switch to a different plan. (This is for security reasons associated with the payment details)

API Request with Authentication

The primary API request domain is https://dsposal.uk/umbraco/api/Compliance, therefore by using the code sample below, you can set the authentication headers.

                

            public static HttpClient GetClient(string username,string password)
            {
                    var authValue = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{password}")));

                    var client = new HttpClient(){
                        DefaultRequestHeaders = { Authorization = authValue}
                        //Set some other client defaults like timeout / BaseAddress
                    };
                    return client;
            }
                

                

Errors

Dsposal uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, authentication failed, etc.). Codes in the 5xx range indicate an error with Dsposal's servers (these are rare, should you encounter those errors, please contact us).

List Compliance Codes

This method returns all the compliance codes, by type.

Sample Request

                        //This sample assumes the use of http://restsharp.org/ for the HTTP request
var domain = "https://dsposal.uk/umbraco/api/Compliance/";

var client = new RestClient(domain);
client.Authenticator = new HttpBasicAuthenticator("your_email", "your_api_key");

var request = new RestRequest("ListCodes", Method.GET);
request.AddParameter("type", "value"); // ewc, ewc_chapters, ewc_subchapters, rd, hp

// Add the json header
request.AddHeader("Accept", "application/json");

// execute the request
IRestResponse response = client.Execute(request);
var content = response.Content; // raw content as string
                
                    

Request Parameters

Parameters Type Description
type
string
Provide the type of codes that will be returned, possible values:
  • ewc (European Waste Catalogue)
  • ewc_chapters (European Waste Catalogue Chapters)
  • ewc_subchapters (European Waste Catalogue Subchapters)
  • rd (Recovery & Disposal Codes)
  • hp (Hazard Property Codes)

Sample Response

                    {
    "Metadata": "Dsposal Compliance API v1 beta",
    "TotalResults": 842,
    "Results": [
        {
            "Code": "01 01 02",
            "CodeType": "ewc_code",
            "EntryType": "Absolute Non-hazardous",
            "CodeDescription": "Wastes from mineral non-metalliferous excavation",
            "Score": 1.0483408
        },
        {
            "Code": "01 03 04*",
            "CodeType": "ewc_code",
            "EntryType": "Absolute Hazardous",
            "CodeDescription": "Acid-generating tailings from processing of sulphide ore",
            "Score": 1.0483408
        },
        {
            "Code": "01 03 05*",
            "CodeType": "ewc_code",
            "EntryType": "Mirror Hazardous",
            "CodeDescription": "Other tailings containing hazardous substances",
            "Score": 1.0483408
        },
        {
            "Code": "01 03 06",
            "CodeType": "ewc_code",
            "EntryType": "Mirror Non-hazardous",
            "CodeDescription": "Tailings other than those mentioned in 01 03 04 and 01 03 05",
            "Score": 1.0483408
        },
        {
            "Code": "01 03 07*",
            "CodeType": "ewc_code",
            "EntryType": "Mirror Hazardous",
            "CodeDescription": "Other wastes containing hazardous substances from physical and chemical processing of metalliferous minerals",
            "Score": 1.0483408
        },
        "Exception": null
    }
                        
                    

Properties

Response Properties
Attributes Type Description
Metadata
string
General API Information
TotalResults
integer
Amount of results returned
Results
List
The results object, see child properties.
Exception
string
System message to display if there is anything wrong with the request, e.g. code type not found
Result List Properties
Attributes Type Description
Code
string
The code name
CodeType
string
The code type
EntryType
string
The code's entry type, CanBeNull
CodeDescription
string
The code's official waste description
Score
float
Score can be used to sorting by relevance, not application when listing all the codes though.

Validate Compliance Codes

This method validates a given compliance code and returnes its properties if found.

Sample Request

                        //This sample assumes the use of http://restsharp.org/ for the HTTP request
var domain = "https://dsposal.uk/umbraco/api/Compliance/";

var client = new RestClient(domain);
client.Authenticator = new HttpBasicAuthenticator("your_email", "your_api_key");

var request = new RestRequest("ValidateCode", Method.GET);
request.AddParameter("type", "value"); // ewc, rd, hp
request.AddParameter("q", "value"); // e.g. 01 01 01, R1, HP1 etc

// Add the json header
request.AddHeader("Accept", "application/json");

// execute the request
IRestResponse response = client.Execute(request);
var content = response.Content; // raw content as string
                
                    

Request Parameters

Parameters Type Description
type
string
Provide the type of codes that will be returned, possible values:
  • ewc (European Waste Catalogue)
  • rd (Recovery & Disposal Codes)
  • hp (Hazard Property Codes)
q
string
Provide the code you wish to validate (query)

Sample Response

                    
{
    "IsValid": true,
    "TotalItems": 1,
    "Results": [
        {
            "Code": "R1",
            "CodeType": "recovery_disposal_code",
            "EntryType": null,
            "CodeDescription": "Use principally as a fuel or other means to generate energy",
            "Score": 8.363837
        }
    ],
    "Exception": null
}
                        
                    

Properties

Response Properties
Attributes Type Description
IsValid
boolean
Boolean to determine whether or not the code has been found
TotalResults
integer
Amount of results returned
Results
List
The results object, see child properties.
Exception
string
System message to display if there is anything wrong with the request, e.g. code type not found
Result List Properties
Attributes Type Description
Code
string
The code name
CodeType
string
The code type
EntryType
string
The code's entry type, CanBeNull
CodeDescription
string
The code's official waste description
Score
float
Score can be used to sorting by relevance, not application when listing all the codes though.

Autocomplete Compliance Codes

This method produces suggestion based on a given input.

Sample Request

                        //This sample assumes the use of http://restsharp.org/ for the HTTP request
var domain = "https://dsposal.uk/umbraco/api/Compliance/";

var client = new RestClient(domain);
client.Authenticator = new HttpBasicAuthenticator("your_email", "your_api_key");

var request = new RestRequest("Autocomplete", Method.GET);
request.AddParameter("q", "value"); // e.g. 01 01 01, General Junk, Acid, etc

// Add the json header
request.AddHeader("Accept", "application/json");

// execute the request
IRestResponse response = client.Execute(request);
var content = response.Content; // raw content as string
                
                    

Request Parameters

Parameters Type Description
q
string
Provide the input you wish to generate suggestions for (query)

Sample Response

                    
{
    "TotalSuggestions": 15,
    "Suggestions": [
        "General Junk",
        "General Waste",
        "General Cladding",
        "General Skip Waste",
        "General Mixed Waste",
        "General Waste Retail",
        "General Office Waste",
        "General Building Rubble",
        "General Demolition Waste",
        "General Commercial Waste",
        "General Industrial Waste",
        "General Restaurant Waste",
        "General Construction Waste",
        "General Administration Waste",
        "General Brickwork And Mortar"
    ]
}
                        
                    

Properties

Response Properties
Attributes Type Description
TotalSuggestions
integer
Amount of results returned
Suggestions
List<string>
A List of strings that match the input.

Compliance Search

This methods allows searching all codes by type, including waste description and Dsposal's Waste Thesaurus.

Sample Request

                        //This sample assumes the use of http://restsharp.org/ for the HTTP request
var domain = "https://dsposal.uk/umbraco/api/Compliance/";

var client = new RestClient(domain);
client.Authenticator = new HttpBasicAuthenticator("your_email", "your_api_key");

var request = new RestRequest("ComplianceSearch", Method.GET);
request.AddParameter("type", "value"); // ewc, rd, hp
request.AddParameter("q", "value"); // e.g. 01 01 01, R1, HP1, General Junk, Acid, etc

// Add the json header
request.AddHeader("Accept", "application/json");

// execute the request
IRestResponse response = client.Execute(request);
var content = response.Content; // raw content as string
                    

Request Parameters

Parameters Type Description
type
string
Provide the type of codes that will be returned, possible values:
  • ewc (European Waste Catalogue)
  • rd (Recovery & Disposal Codes)
  • hp (Hazard Property Codes)
q
string
Provide the search input, e.g. General Junk, Acid, etc.

Sample Response

For EWC Codes
                    
{
    "Metadata": "Dsposal Compliance API v1 beta",
    "TotalResults": 2,
    "Results": [
        {
            "CodeLogo": "",
            "Chapter": "20",
            "ChapterDescription": "municipal wastes ...",
            "SubChapter": "20 03",
            "SubChapterDescription": "other municipal wastes",
            "Code": "20 03 07",
            "CodeType": "ewc_code",
            "EntryType": "Absolute Non-hazardous",
            "CodeDescription": "bulky waste",
            "Score": 2.45919919
        },
        {
            "CodeLogo": "",
            "Chapter": "20",
            "ChapterDescription": "municipal wastes ...",
            "SubChapter": "20 03",
            "SubChapterDescription": "other municipal wastes",
            "Code": "20 03 01",
            "CodeType": "ewc_code",
            "EntryType": "Absolute Non-hazardous",
            "CodeDescription": "mixed municipal waste",
            "Score": 2.45919919
        }
    ],
    "Exception": null
}
                        
                    
For HP & RD Codes
                    
{
    "Metadata": "Dsposal Compliance API v1 beta",
    "TotalResults": 1,
    "Results": [
        {
            "Code": "HP4",
            "CodeType": "hazard_property_code",
            "EntryType": "Irritant",
            "CodeDescription": "- Waste which on application can cause skin irritation or damage to the eye...
            "Score": 3.81211185
        }
    ],
    "Exception": null
}
                        
                    

Properties

Response Properties
Attributes Type Description
Metadata
string
General API Information
TotalResults
integer
Amount of results returned
Results
List
The results object, see child properties for EWC Results, or see child properties for HP & RD Results.
Exception
string
System message to display if there is anything wrong with the request, e.g. code type not found
Result List Properties EWC
Attributes Type Description
Chapter
string
The chapter that the code belongs to
ChapterDescription
string
The description of the chapter that the code belongs to
Subchapter
string
The subchapter that the code belongs to
SubchapterDescription
string
The description of the subchapter that the code belongs to
Code
string
The code name
CodeType
string
The code type
EntryType
string
The code's entry type
CodeDescription
string
The code's official waste description
CodeLogo
string
Link to a custom logo created by Dsposal for the given EWC Code CanBeNull
Score
float
Score can be used to sorting by relevance, not application when listing all the codes though.
Result List Properties RD & HP
Attributes Type Description
Code
string
The code name
CodeType
string
The code type
EntryType
string
The code's entry type, CanBeNull
CodeDescription
string
The code's official waste description
Score
float
Score can be used to sorting by relevance, not application when listing all the codes though.