📜API Reference

A walk through of the prerequisites and contextual knowledge you need to make Plasteax queries.

This guide provides everything you need to access and work with plastic packaging end-of-life data. The Plasteax API offers researchers, sustainability professionals, and developers a powerful way to analyze and integrate plastic waste data into their applications and research. Whether you're building sustainability dashboards, conducting environmental impact assessments, or researching plastic waste flows, this API provides standardised, comprehensive data to support your work.

Requirements

• Access to the API endpoint (see section API endpoints for more details).

• Familiarity with curl or other ways of interacting with HTTP APIs like Postman, Bruno, or directly from this page (see below).

API endpoints

There are two environments that can be explored using Plasteax API. The production environment provides access to the official Plasteax dataset, which requires an access key available exclusively through a Plasteax subscription. The demo environment which offers unrestricted access to mock data for all Plasteax metrics.

PROD:

https://d0ks2qopw9.execute-api.eu-west-3.amazonaws.com/plasteax

All code examples in this documentation use the demo API for illustration. The methods described here can be directly applied to the production environment too.

Important: The demo (testing) API provides fake values. Do not use these values for real-world plastic footprints.

Introduction to plastic waste data concepts

The Plasteax API provides data about plastic packaging at its end-of-life stage. Understanding a few key concepts will help you make effective use of this API:

Datasets

A dataset is the core resource in this API, containing facts about what happens to plastic packaging when it reaches the end of its useful life.

Dimensions

Each dataset is characterised by these four dimensions which you can use as filters:

• Country: 3-letter ISO code (e.g., "FRA" for France)

• Category: Product category (e.g., "Rigid non-food packaging")

• Polymer: Type of plastic (e.g., "PET")

• Year: Time period of data collection (e.g., 2020)

Data types

End-of-life data in includes two types of information:

• Material quantities: Masses of material expressed in kilo-tonnes (kt). E.g., the total production and import of packaging for a given country.

• Ratios: Percentages representing the proportion of materials with specific fates. E.g., the percentage of total production of a material that is leaked into ocean and waterways.

Data dictionary

The API returns the following fields:

Material quantities (in kt)

• production_and_import: Total production and import of packaging

• export: Export of packaging

• added_stock: Material added to existing stock

• waste_import: Import of waste from other countries

• reexport_of_waste_import: Re-export of imported waste

• recycling_of_waste_import: Recycling of imported waste

• proper_disposal_of_waste_import: Proper disposal of imported waste

• improper_disposal_of_waste_import: Improper disposal of imported waste

• waste_produced_in_the_country: Waste generated domestically

Ratios (in percent)

• domestic_recycling_of_collected: Percentage recycled within the country

• export_of_collected: Percentage exported for processing

• incineration_and_energy_recovery: Percentage incinerated for energy

• sanitary_landfill: Percentage sent to proper landfills

• improperly_disposed: Percentage disposed improperly

• littering: Percentage directly littered

• uncollected_excluding_littering: Percentage not collected (excluding litter)

• total: Overall percentage (should sum to 100%)

• collected: Percentage of waste collected

• mismanaged_including_littering: Percentage mismanaged (includes littering)

• leaked_to_ocean_and_waterways: Percentage entering oceans and waterways

Dimensions

A dataset is characterised by several dimensions:

• country

• category

• polymer

• year

The API allows one to filter datasets along those dimensions to retrieve as specific or as broad a dataset as you require.

API requests

With all of that in mind here are some example requests.

Get datasets

To get all available datasets, run the following command.

curl -L "https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/datasets"

You can filter the results by a specific dimension using query parameters.

curl -L "https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/datasets?year=2020"

Or try running requests directly from this page.

Returns all datasets.

get

Query parameters

countrystringOptional

3-letter ISO code of a country

Example: FRA

categorystringOptional

Product category

Example: Rigid non-food packaging

polymerstringOptional

Polymer

Example: PET

yearintegerOptional

Time period

Example: 2020

pageintegerOptional

Page index (starting from 0)

Default: 0Example: 2

page_sizeintegerOptional

Page size

Default: 100Example: 100

Responses

200

Successful operation

application/json

400

The request is invalid

get

/datasets

HTTPcURLJavaScriptPython

GET /plasteax/datasets HTTP/1.1
Host: 2oqef6q7rg.execute-api.eu-west-3.amazonaws.com
Accept: */*

{
  "pagination": {
    "total-items": 0
  },
  "elements": [
    {
      "country": "FRA",
      "category": "Rigid non-food packaging",
      "polymer": "PET",
      "year": 2021,
      "production_and_import": {
        "amount": 1,
        "unit": "kt"
      },
      "export": {
        "amount": 1,
        "unit": "kt"
      },
      "added_stock": {
        "amount": 1,
        "unit": "kt"
      },
      "waste_import": {
        "amount": 1,
        "unit": "kt"
      },
      "reexport_of_waste_import": {
        "amount": 1,
        "unit": "kt"
      },
      "recycling_of_waste_import": {
        "amount": 1,
        "unit": "kt"
      },
      "proper_disposal_of_waste_import": {
        "amount": 1,
        "unit": "kt"
      },
      "improper_disposal_of_waste_import": {
        "amount": 1,
        "unit": "kt"
      },
      "waste_produced_in_the_country": {
        "amount": 1,
        "unit": "kt"
      },
      "domestic_recycling_of_collected": {
        "amount": 10,
        "unit": "percent"
      },
      "export_of_collected": {
        "amount": 10,
        "unit": "percent"
      },
      "incineration_and_energy_recovery": {
        "amount": 10,
        "unit": "percent"
      },
      "sanitary_landfill": {
        "amount": 10,
        "unit": "percent"
      },
      "improperly_disposed": {
        "amount": 10,
        "unit": "percent"
      },
      "littering": {
        "amount": 10,
        "unit": "percent"
      },
      "uncollected_excluding_littering": {
        "amount": 10,
        "unit": "percent"
      },
      "total": {
        "amount": 10,
        "unit": "percent"
      },
      "collected": {
        "amount": 10,
        "unit": "percent"
      },
      "mismanaged_including_littering": {
        "amount": 10,
        "unit": "percent"
      },
      "leaked_to_ocean_and_waterways": {
        "amount": 10,
        "unit": "percent"
      }
    }
  ]
}

Get reference data

The reference data include the available countries, product categories, polymers and years. You can fetch it using

curl -L 'https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/reference-data'

Or try running requests directly from this page.

Returns the reference data.

get

Responses

200

Successful operation

application/json

400

The request is invalid

get

/reference-data

HTTPcURLJavaScriptPython

GET /plasteax/reference-data HTTP/1.1
Host: 2oqef6q7rg.execute-api.eu-west-3.amazonaws.com
Accept: */*

{
  "countries": [],
  "categories": [],
  "polymers": [],
  "years": []
}

Get metadata

The metadata includes the versions of the various databases as well as a list of reference papers that were used as data sources to build the Plasteax database. A quality score is also given to each reference paper.

curl -L "https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/metadata"

Or try running requests directly from this page.

Returns metadata about this version of Plasteax

get

Responses

200

Success

application/json

get

/metadata

HTTPcURLJavaScriptPython

GET /plasteax/metadata HTTP/1.1
Host: 2oqef6q7rg.execute-api.eu-west-3.amazonaws.com
Accept: */*

200

Success

{
  "baciVersion": "HS17_V202301",
  "sourceQualityData": []
}

Pagination

When retrieving datasets, you can navigate through results using pagination:

1. Set the page_size parameter to control how many results to return per request

2. Start with page=0 for the first page of results

3. Check the pagination.total-pages value in the response to know how many pages exist

4. Increment the page parameter to navigate to subsequent pages

For additional support or to report issues, please contact the Plasteax team directly.