# API Reference 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](https://curl.se/) or other ways of interacting with HTTP APIs like [Postman](https://www.postman.com/), [Bruno](https://www.usebruno.com/), 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. {% hint style="warning" %} Important: The demo (testing) API provides fake values. Do not use these values for real-world plastic footprints. {% endhint %} ## 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. ```bash 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. ```bash curl -L "https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/datasets?year=2020" ``` Or try running requests directly from this page. {% openapi src="/files/U3EvITaT2IBwRvi60cfk" path="/datasets" method="get" %} [openapi.yaml](https://2560226434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fwy4KdoRRfCaMqTG1tUD4%2Fuploads%2Fgit-blob-6002c00511dcb5ceabecffa4feecbc915360c627%2Fopenapi.yaml?alt=media) {% endopenapi %} ### Get reference data The reference data include the available countries, product categories, polymers and years. You can fetch it using ```bash curl -L 'https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/reference-data' ``` Or try running requests directly from this page. {% openapi src="/files/U3EvITaT2IBwRvi60cfk" path="/reference-data" method="get" %} [openapi.yaml](https://2560226434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fwy4KdoRRfCaMqTG1tUD4%2Fuploads%2Fgit-blob-6002c00511dcb5ceabecffa4feecbc915360c627%2Fopenapi.yaml?alt=media) {% endopenapi %} ### 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. ```bash curl -L "https://2oqef6q7rg.execute-api.eu-west-3.amazonaws.com/plasteax/metadata" ``` Or try running requests directly from this page. {% openapi src="/files/U3EvITaT2IBwRvi60cfk" path="/metadata" method="get" %} [openapi.yaml](https://2560226434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fwy4KdoRRfCaMqTG1tUD4%2Fuploads%2Fgit-blob-6002c00511dcb5ceabecffa4feecbc915360c627%2Fopenapi.yaml?alt=media) {% endopenapi %} ### 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.plasteax.earth/api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.