📜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

DEMO:

https://2oqef6q7rg.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
get
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
get
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
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.

PreviousWhat is Plasteax?NextOverview

Last updated

Was this helpful?