emanifest

e-Manifest

emanifest is a client library for accessing the e-Manifest REST APIs of the US Environmental Protection Agency's RCRAInfo national electronic hazardous waste management system.

Contents

• Requirements
• Installation
• Getting Started
  • Authentication
  • Methods
  • Regulator Usage
  • Advanced Usage
• Contact
• License

Requirements

• Python 3.10 or higher

Installation

emanifest can be installed directly from the Python package Index (PyPI) using pip:

$ pip install emanifest

Getting Started

Before using the emanifest package, ensure you have a RCRAInfo user account and the necessary permissions to generate an API ID and key.

All methods to access the e-Manifest APIs are implemented by the RcrainfoClient class which needs your API ID and key to authenticate. A new instance of the class can be initiated like so:

from emanifest import new_client

rcrainfo = new_client('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')

That's it! You're ready to start using the RCRAInfo Restful web services.

The RcrainfoClient class requires one positional argument, a string, either 'preprod', or 'prod'.

Authentication

The RcrainfoClient can be explicit configured to automatically authenticate as needed with the auto_renew keyword argument. By default, this behavior is disabled. If auto_renew is disabled, you must explicitly call the authenticate method.

from emanifest import new_client

rcrainfo = new_client('preprod', api_id='my_api_id', api_key='my_api_key', auto_renew=True)
rcrainfo.get_site('VATEST000001')  # This will automatically authenticate if needed.
print(rcrainfo.is_authenticated)  # True

The RcrainfoClient stores the security token, its expiration (20 minutes), and will request a new token once expired.

Methods

After providing your API credentials, you are ready to use the full functionality of the emanifest package. The RcrainfoClient class exposes a method for each API endpoint following an <action>_<resource> naming convention.

Examples:

RCRAInfo endpoints that require a URL parameter should be passed as a string to the RcrainfoClient method.

from emanifest import new_client

rcrainfo = new_client('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')

# Use the rcrainfo auth service to retrieve a security token.
if not rcrainfo.is_authenticated:
    rcrainfo.authenticate()

# Any endpoint with URL parameters will take that parameter as a positional, string argument.
site_resp = rcrainfo.get_site('VATEST000001')

Many of the POST request use keyword arguments to compose the http request's body. For example:

from emanifest import new_client

rcrainfo = new_client('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY', auto_renew=True)

resp = rcrainfo.search_mtn(siteId='VATEST000001', status='InTransit')

would send a http requests with the following body to the manifest tracking number (mtn) search endpoint.

{
  "siteId": "VATEST000001",
  "status": "InTransit"
}

Keyword arguments use the same naming convention seen in the RCRAInfo Swagger pages and services documentation.

multipart/mixed payloads ( e.g., JSON of a manifest and .zip file of attachments) can be uploaded to RCRAInfo by passing a dictionary and the bytes of the optional attachment like so:

from emanifest import new_client
import json

rcrainfo = new_client('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY', auto_renew=True)

# The dictionary and .zip file could come from a database, filesystem, an external service,
# or json.load({'manifestTrackingNumber': '0123456789ELC', ... })
with open('./attachments.zip', 'rb') as f:
    attachment = f.read()
with open('./manifest.json', 'r') as f:
    manifest_json = json.loads(f.read())

resp = rcrainfo.update_manifest(manifest_json, attachment)

Responses are returned as a RcraResponse object, which wraps around the requests library Response object. Methods that download file attachments can be accessed via the RcrainfoResponse.json() method and RcrainfoResponse.zip property when appropriate. The entire request.Response object is returned in RcrainfoResponse.response.

from emanifest import new_client

rcrainfo = new_client('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY', auto_renew=True)

resp = rcrainfo.get_manifest_attachments('123456789ELC')

# RcraInfoResponse re-exports a couple attributes of the requests.Response object.
print(resp.ok)
# Or you can access the full Response like such...
print(resp.response.json())
# For endpoints that return multipart/mixed bodies, you can access JSON with the resp.json()
downloaded_json = resp.json()
# The .zip file can be accessed in the resp.zip property.
downloaded_attachment = resp.zip

Regulators

Starting with version 3.0 and above of this package, regulatory users can use the same methods as industry but with the reg keyword argument set to True. For example:

from emanifest import new_client

rcrainfo = new_client('preprod', api_id='YOUR_API_ID', api_key='YOUR_API_KEY')

resp = rcrainfo.get_manifest('123456789ELC', reg=True)

The reg keyword argument is set to False by default. The following methods have regulator options:

1. get_manifest_attachments
2. search_mtn
3. get_correction
4. get_correction_version
5. get_site_mtn
6. get_manifest
7. get_sites

The following methods are for regulatory users only:

1. get_handler
2. get_cme_lookups
3. get_cme_indicators
4. get_cme_types

API endpoints designed for use by other groups, such as regulators or industry users, will return 'Access Denied' errors if you are not authorized to access these resources in RCRAInfo.

Advanced Usage and Help

As of version 3.0, the RcrainfoClient is a subclass of the requests library Session Class which allows you to take advantage of its functionality.

RcrainfoClient can be also customized by subclassing and overriding. For example:

from emanifest import RcrainfoClient


class MyClass(RcrainfoClient):
    def retrieve_id(self, api_id=None) -> str:
        # Custom behavior to retrieve your RCRAInfo API ID
        my_api_id = 'api_id_from_someplace_secure'
        return super().retrieve_id(my_api_id)

For RcrainfoClient method specific documentation, you can use the help() function from the Python console to get a description of each method and its inputs.

>>> from emanifest import RcrainfoClient
>>> help(RcrainfoClient.get_bill)

For more information about the RCRAInfo services, see the documentation in the root directory of the e-Manifest GitHub repo, and the Swagger page of your selected environment (Preproduction, Production). Do not use the RCRAInfo Production environment for testing. To register for a testing account in preproduction, visit the preprod site.

Contact

Please direct questions to the EPA e-Manifest team at USEPA/e-manifest

Disclaimer

The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. EPA has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality, or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA. The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government.