📜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

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

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

baciVersionstringOptionalExample: HS17_V202301

get

/metadata

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:

Set the page_size parameter to control how many results to return per request
Start with page=0 for the first page of results
Check the pagination.total-pages value in the response to know how many pages exist
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 9 months ago